Make a Payment

POST /alternatepayments/v1/accounts/account_id/payments

To authorize a payment you must make a POST request to the payments endpoint.

If the payment type supports the manual settlement flow, you must also provide the settleWithAuth parameter, with the value set to false so that it will be settled later.

Do not rely on the on_completed URL in the returnLinks object to release goods or money, because there are no security checks to prevent customers from accessing this URL directly. Instead, you verify the Settlement status for the payment or configure a webhook.

The following example shows a sample request, in this case for a BOKU payment.

Request Example
curl -X POST https://api.test.paysafe.com/alternatepayments/v1/accounts/1001070130/payments \
 -u testuser:B-qa2-0-53625f86-302c021476f52bdc9deab7aea876bb28762e62f92fc6712d0214736abf501e9675e55940e83ef77f5c304edc7968 \
 -H 'Content-Type: application/json' \
 -d
{
  "merchantRefNum": "UniqueRef1234",
  "dupCheck": true,
  "amount": 100,
  "currencyCode": "EUR",
  "profile": {
    "firstName": "Stan",
    "lastName": "Smith",
    "email": "stan.smith@fox.com",
    "ip": "127.0.0.1"
  },
  "billingDetails": {
    "street1": "Street line 1",
    "street2": "Street line 2",
    "city": "Voorst",
    "state": "DR",
    "country": "NL",
    "zip": "T3H3L3"
  },
  "returnLinks": [
      "rel": "default",
    {
      "href": "https://mysite.com/return"
    }
  ],
  "paymentType": "BOKU",
  "boku": {
      "descriptor": "custom descriptor",
      "consumerId": "CUS_12345678",
      "consumerCountry": "GB",
      "consumerMobilePhone": "44292102029"
    }
  }
}

The amount is specified in minor units of the currency of the merchant account, which is inferred from the account_id parameter in the URL. For example, to process US $10.99, this value should be 1099. To process 1000 Japanese yen, this value should be 1000. To process 10.139 Tunisian dinar, this value should be 10139.

Prior to trying the example above, you should:

  • Provide a unique merchant reference number (merchantRefNum) for each transaction.
  • Replace the account number (1001070130) in the URL with the Test account number you received for the alternate payments method you are testing.
  • Replace the API key (after the -u) with the Test API key you have received.

The parameters to include for the paymentType object vary, depending on which payment type you are using. For full details about each payment type, please consult our integration documentation.

Response Example
{
  "id": "9cc5376a-57b8-4351-b42c-3a02a1040b21",
  "merchantRefNum": "UniqueRef1234",
  "dupCheck": true,
  "amount": 100,
  "currencyCode": "EUR",
  "profile": {
    "firstName": "Stan",
    "lastName": "Smith",
    "email": "stan.smith@fox.com",
    "ip": "127.0.0.1"
  },
  "billingDetails": {
    "street1": "Street line 1",
    "street2": "Street line 2",
    "city": "Voorst",
    "state": "DR",
    "country": "NL",
    "zip": "T3H3L3"
  },
  "returnLinks": [
    {
      "rel": "default",
      "href": "https://mysite.com/return"
    }
  ],
  "liveMode": "false",
  "txnTime": "2015-12-11T16:33:49Z",
  "status": "INITIATED",
  "gatewayResponse": {
    "code": "000.100.110",
    "description": "Request successfully processed in 'Merchant in Integrator Test Mode'",
    "paymentType": "RF"
  },
  "paymentType": "BOKU",
  "boku": {
      "descriptor": "custom descriptor",
      "consumerId": "CUS_12345678",
      "consumerCountry": "GB",
      "consumerMobilePhone": "44292102029"
    }
  },
  "links": [
    {
      "rel": "self",
      "href": "https://api.paysafe.com/alternatepayments/v1/accounts/1001070130/payments/9cc5376a-57b8-4351-b42c-3a02a1040b21\""
    },
    {
      "rel": "redirect_payment",
      "href": "https://api.paysafe.com/alternatepayments/v1/accounts/1001070130/payments/9cc5376a-57b8-4351-b42c-3a02a1040b21/redirect?token=eyJhbGciOiJIUzI1NiJ9.eyJhdGQiOiI5Y2M1Mzc2YS01N2I4LTQzNTEtYjQyYy0zYTAyYTEwNDBiMjEiLCJhY2QiOiIxNDY1MzMwMTAyIiwiZXhwIjoxNDY1NDAwNjg2fQ.EzLIFiXt40PLVuX7SOHRkZrNX7Nn0_97ZJsGx1yKRrc"
    }
  ]
}

The payment response contains the following parameters:

Value Type Description
id string This is a unique ID for this payment operation. You can use it, e.g., to look up a payment request.
merchantRefNum string This is the merchant reference number created by the merchant and submitted as part of the request.
dupCheck boolean

true indicates this is not a duplicate transaction.

A request is considered a duplicate if the merchantRefNum has already been used in a previous request within the past 90 days.

amount integer This is the amount of the request, in minor units.
currencyCode enum

This is the three-digit currency code for the currency of the merchant account specified by the account_id in the request URL.

profile object These are some details about the customer.
billingDetails object These are some billing details for the request.
returnLinks array of link objects

This is a TLS-secured endpoint to return the customer to at the completion of the request.

liveMode boolean

true indicates this is a real transaction.

false indicates this is a test transaction.

txnTime dateTime This is the transaction time and date in UTC format.
status enum

This is the status of the payment, set to INITIATED by default.

  • CANCELLED – The authorization request has been fully reversed.
  • COMPLETED – The transaction has been completed.
  • ERROR – The transaction failed due to an error (e.g., missing required parameter).
  • EXPIRED – The authorization of the payment or the payment initiation has expired.
  • FAILED – The transaction was declined.
  • INITIATED – The request has been initiated by the payment provider and is awaiting customer authorization.
  • PROCESSING – The request was authorized by the customer, awaiting payment provider authorization.
  • RECEIVED – Our system has received the request and is waiting for the payment provider's response.
gatewayResponse object This contains the response from the payment provider and varies depending on the payment method used.
paymentType enum This is the payment type used for the request (e.g., BOKU).
boku object These are BOKU attributes that were passed that when making the payment request.
links array of link objects
  • The array contains a self link that can be used to look up details about the request.
  • For payment methods with a redirect flow, the array contains a unique, securely encrypted
    redirect_payment link provided by Paysafe to which the customer can be redirected to confirm payment.

Did you find this page useful?