Skip to main content

Collect Payment

Overview​

This tutorial covers the customer-initiated charge, where the customer is at your checkout. Because the customer is present, the charge runs on a fresh token, not on a saved payment instrument. For charges made without the customer (upsells, retries), see Card on file.

Prerequisites​

You need a Customer and a fresh tokenization token. See Create a customer for the customer record and When to use FramePay vs server-side for how to tokenize the card.

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

Create transaction​

To create transaction specify parameters in the Transactions API call:

type - "sale" to collect payment
customerId - ID of customer created before
currency - currency of transaction
amount - amount of transaction
redirectUrl - URL to redirect customer after transaction is completed. Not enforced, but set it: without it the customer returns to a fallback URL configured on the account.
isMerchantInitiated - false, because the customer is present
paymentInstruction :

  • token - a fresh token from the tokenization step. Single-use: this transaction consumes it.

Example:

curl --location 'https://staging-api.payments.ai/v1/public-api/organizations/${ORGANIZATION_ID}/transactions' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey ${API_KEY}' \
--data '{
    "customerId": "${CUSTOMER_ID}",
    "currency": "USD",
    "amount": 10,
    "type": "sale",
    "paymentInstruction": {
        "token": "${TOKEN}"
    },
    "isMerchantInitiated": false,
    "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: paymentLink. 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",
        "paymentLink": "https://3ds.example/...",
        ...
    }
}

If the status is waiting, check for the paymentLink 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.

Charging the same customer again​

The response contains a paymentInstrument object. Once this transaction's final result is approved, its id is a stored instrument you can charge without the customer present (an upsell or a retry) by sending paymentInstrumentId with isMerchantInitiated: true.

If the customer is back at your checkout, tokenize again and repeat this tutorial instead. A returning customer is still customer-present.

For the full customer-initiated to merchant-initiated sequence, see Card on file.

Transaction Lifecycle​