Create a Payment

What is a Payment?

When the user wants to perform a purchase in you platform, you need to initiate a Payment in Ping. A Payment represents a single attempt of purchase. In this request you provide key information such as amount, payment method and recipients.

Example

Example showing how to initiate a card payment and what response you will get.

Request

curl --location 'https://sandbox.pingpayments.com/payments/api/v1/payment_orders/<YOUR-PAYMENT-ORDER-ID>/payments' \
--header 'x-api-secret: <YOUR-API-SECRET>' \
--header 'tenant_id: <YOUR-TENANT-ID>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "order_items": [
      {
        "amount": 29900,
        "metadata": {},
        "name": "Test Purchase",
        "merchant_id": <YOU-MERCHANT-ID>,
        "vat_rate": "0",
        "tags": []
      }
    ],
    "payer": {
        "name": "John Doe",
    },
    "provider_method_parameters": {
        "error_url": "https://<YOUR-DOMAIN>/error/",
        "success_url": "https://<YOUR-DOMAIN>/success/",
        "cashier": {}
    }, 
    "metadata": {},
    "currency": "SEK",
    "method": "card",
    "provider": "payment_iq",
    "status_callback_url": "https://<YOUR-DOMAIN>/ping-callback/payment_status",
    "total_amount": 29900
}'

Response

{
    "id": "c7a35333-7d56-4fc7-8f68-67a7f8f7a0a3",
    "provider_method_response": {
        "pay_url": "https://piq-sandbox.pingpayments.com/pay/EdDAb27i?locale=en-US"
    }
}

Parameters

Request Parameters

Name	Description
`currency`	ISO 4217 currency code for all underlying Payments (e.g. EUR, SEK). Must be the same as the PaymentOrder currency.
`metadata`	Metadata from your domain. We encourage to provide as much as possible since it is useful in support cases.
`method`	The payment method for the selected provider. (more information in next section)
`provider`	The payment provider which facilitates the payment. (more information in next section)
`provider_method_parameters`	Specific information required for the selected payment method. (more information in next section)
`order_items`	Items of purchase and who the recipient is. See InitiatePayment for the full specification.
`payer`	The individual/organization which is performing the payment. Populate this as thorough as you can.
`status_callback_url`	The URL which Ping will send callbacks to regarding the specific payment.
`total_amount`	The total amount in minor currency unit. For example 10000 represent 100 in a euro payment. This amount must sum with all the amount's in the `order_item` list.

Response Parameters

Name	Description
`id`	The ID of the Payment.
`provider_method_response`	Information forwarded from the payment provider. In the example above this includes a url to a checkout.

Selecting a Payment Method

To select and successfully initiate a payment with a specific payment method three fields are relevant, provider, method and provider_method_parameters

By combining provider and method you can select which payment method will be used for the payment. The provider_method_parameters is specific information for the selected payment method which the payment provider relies on.

Provider Method Mapping

Provider	Method	Payment type	Description
`swish`	`e_commerce`	mobile, immediate	Swish e-commerce payments use the payer’s number and await confirmation in the Swish app - display a spinner prompting users to open Swish to complete.
`swish`	`m_commerce`	mobile, immediate	Swish m-commerce payments aren’t pre-seeded with the payer’s number—users scan a QR code or launch the Swish app via its URL schema to complete the payment.
`payment_iq`	`card`	card payment, immediate	Regular card payments provided through PaymentIQ (Worldline).
`ping`	`deposit`	bank transfer, (0-2 banking days)	Generic bank transfers use reference numbers; the payment completes once the funds hit your Ping account.
`bankgirot`	`autogiro`	account-to-account, bank settlements (1-2 banking days	Traditional Swedish mandate payment method, commonly used for recurring payments.

Status callback

Ping will post callbacks to the provided status_callback_urlto let you now the exact state of the payment so you can react accordingly. The possible status of a payment are INITIATED, PENDING, COMPLETED, CRASHED, ABORTED, EXPIRED, DECLINED. STOPPED, UNDERFUNDED, OVERFUNDED & FUNDED. Note that all statuses are note applicable for all payment methods, please see the table below.

Note: To ensure robust callbacks ping will make up to 20 attempts with exponential back off to make sure the callback is allays delivered.

Status	Type	Description
INITIATED	non-terminated	The initial status of the callback. No callback will be sent for this status.
PENDING	non-terminated	If the payment is successfully initiated the status will transition to PENDING, which indicates that the payment is ongoing.
COMPLETED	terminated	The payer has successfully paid the full amount of the payment.
CRASHED	terminated	The payment crashed due to a provider error.
ABORTED	terminated	The payer did not go through with the payment.
EXPIRED	terminated	The payment was not paid in time.
DECLINED	terminated	The payment was declined by the provider. No callback will be sent for this status.
STOPPED	terminated	The payment was manually stopped. This action is performed by the tenant to stop an PENDING payment. No callback will be sent for this status.
UNDERFUNDED	non-terminated	Indicates that the payer paid less than the payment amount. This status is only relevant for `ping/deposit`payments.
OVERFUNDED	non-terminated	Indicates that the payer paid more than the payment amount. This status is only relevant for `ping/deposit`payments.
FUNDED	non-terminated	Indicates that the payer paid the expected payment amount. This status is only relevant for `ping/deposit`payments when the provider_method_parameter `complete_when_funded` is set to false.

Note: Once a payment is terminated, no more status-callbacks will be sent regarding that payment

If you would for example receive the status CRASHED you should indicate for the user that the payment did not go through. If the user still want's to go through with the purchase, an new payment needs to be initiated.

Authenticate the callback

Ping offers an optional callback-signature feature for added security. When enabled, you can verify that every callback truly originates from Ping and hasn’t been tampered with. See SigningKeys for more information

Note: This signature verification applies to all Ping callbacks—not just payment-status updates.