Create a Payment

What is a Payment?

When a user initiates a purchase on your platform, you create a Payment in Ping. A Payment represents a single attempt to complete a transaction. As part of the request, you specify key details such as the amount, selected payment method, and the intended recipients.

Example

Here’s a concise example of how to initiate a card payment using Ping, along with the structure of a typical response.

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 match the associated PaymentOrder's currency.
`metadata`	Metadata from your domain. We encourage to provide as much information as possible, as it greatly assists in support cases, allowing us to partly speak your domain language.
`method`	The payment method for the selected provider. More information in the next section.
`provider`	The payment provider which facilitates the payment. More information in the next section.
`provider_method_parameters`	Parameters specific to the selected payment method. More information in the next section.
`order_items`	Contains information about each item of purchase, like who the recipient is, the amount and the VAT rate. See InitiatePayment for the full specification.
`payer`	The individual/organization who is performing the payment. For KYC purposes, we require you to provide as much detail as possible. Depending on the case, we may ask you for specific information.
`status_callback_url`	The URL to which Ping will send notifications (callbacks) pertaining to the Payment.
`total_amount`	The total amount specified in Minor Currency Unit (MCU). For EUR, this is Cents. So a value of 100000 EUR in MCU (cents) is equivalent to €1000.00. This amount must match the sum of all the `order_item` amounts.

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 required, 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 required for the selected payment method on which the payment provider relies.

Provider Method Mapping

Provider	Method	Payment type	Description
`swish`	`e_commerce`	mobile, immediate	Swish e-commerce payments using the payer’s number which awaits confirmation in the Swish app—display a spinner prompting users to open Swish to complete.
`swish`	`m_commerce`	mobile, immediate	Swish m-commerce payments without pre-seeded payer number—display a QR code for scanning or launch the Swish app via deep links to complete the payment.
`payment_iq`	`card`	card payment, immediate	Regular card payments provided through PaymentIQ (Worldline). Redirect the user to the provided payment URL for them to complete the payment.
`ping`	`deposit`	bank transfer, (0-2 banking days)	Generic bank transfers using reference numbers (OCR, KID). The payment completes once the funds have been received in 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 make callback requests to the provided status_callback_url to notify you about the current state of the Payment in order for you to react accordingly. Below are the available Payment statuses.

Note: Some statuses are referred to as "terminal", meaning that once reached, the status is guaranteed to never change. It's a final status update meaning the acquiring transaction has reached the end of its lifetime (terminated).

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	Terminal	Description
INITIATED	No	The initial status of the Payment. No callback will be sent for this status.
PENDING	No	After a successful initiation of a Payment, the status will transition to PENDING, which indicates that the payment is ongoing.
COMPLETED	Yes	The payer has successfully paid the full amount of the Payment.
CRASHED	Yes	The Payment crashed due to a provider error.
ABORTED	Yes	The payer did not go through with the Payment.
EXPIRED	Yes	The Payment was not paid within the Payment session lifetime. This time varies between payments methods.
DECLINED	Yes	The Payment was declined by the provider. Like the INITIATED status, no callback will be sent for this if the Payment failed to intiate.
STOPPED	Yes	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	No	Indicates that Ping received less funds than required for the Payment amount. Only relevant for `ping/deposit` Payments where the amount deposited is out of Ping's control.
OVERFUNDED	No	Indicates that Ping received more funds than the Payment amount. Only relevant for `ping/deposit` Payments where the amount deposited is out of Ping's control.
FUNDED	No	Indicates that Ping received 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`.

For example, if you would receive the status CRASHED you should notify the user that the Payment did not go through. If the user wants to try again, a 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.