Skip to main content

Collect Payment

Overview​

Prerequisites​

You need to have a Customer with an attached Payment Instrument. Please follow this tutorial to fulfill these requirements.

It would be helpful if you copy customerId and paymentInstrumentId to use it with the transaction request.

Create transaction​

To create transaction specify parameters in the Transactions API call:

type - "sale" to collect payment
customerId - ID od customer created before
currency - currency of transaction
amount - amount of transaction
redirectUrl - URL to redirect customer after transaction is completed. This is optional. paymentInstruction :

  • paymentInstrumentId - ID of payment instrument attached to customer

Example:

curl --location 'https://staging-api.payments.ai/v1/public-api/organizations/:organizationId/transactions' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey <keyValue>' \
--data '{
    "customerId": "{{customerId}}",
    "currency": "USD",
    "amount": "10",
    "type": "sale",
    "paymentInstruction": {
        "paymentInstrumentId": "{{paymentInstrumentId}}"
    },
    "redirectUrl": "https://yourwebsite.com/{id}/{result}"
}'

Redirect customer to payment confirmation​

After you have successfully created the transaction you will get in the response the confirmation link. It is located inside the data object and called: approvalLink. You need to redirect the customer to that link.

Redirect customer back to your website​

After the transaction is completed, the customer will be redirected to the URL you provided in the redirectUrl parameter. Example https://yourwebsite.com/{id}/{result}:

  • {id} - Will be automaticly populated with transaction ID
  • {result} - Will be populated with the reason of the transaction (e.g. success, decline)

3DSecure​

When a transaction requires 3D Secure (3DS) authentication, the response will contain the following structure:

{
    "data": {
        ...
        "status": "waiting",
        "result": "unknown",
        "approvalLink": "https://3ds.example/...",
        ...
    }
}

If the status is waiting, check for the approvalLink and redirect the customer to that URL. The customer will be taken to the 3D Secure page to approve the transaction. Once completed, they will be redirected back to the URL specified in the redirectUrl parameter.

If the card does not require 3D Secure, the transaction will have a status of completed, and no further action from the customer is necessary.

Transaction Lifecycle​