Making Your First API Call

This section provides a step-by-step explanation of how to make your first API call.

Merchant Account Credentials

Most API calls – but not all – require you to include the following credentials :

Credentials Description Example
API Key

Your API key is available in two forms:

  • Username and password; or
  • Base64 encoded

Username – 66040-1001062690

Password – B-qa2-0-579b6aec-0-606c02147caae097f4392898ca08ae736e51d3093af388d90214528ac70b69c0359d3173d12480d07275ca54a7c7

Account Number

This is a unique account number, which must be included in Card Payments, 3D Secure, Direct Debit, and Alternate Payments API requests, but is not needed for other types of API requests. Different accounts support different payment method/currency combinations.

1001062690

Your API key credentials (user name and password) are not the same as the user name and password you use to sign in to the Merchant Back Office.
Each merchant account has a single primary API key (the server-to-server API key) used by the majority of API calls.

Example

The code snippet below provides an example of the above credentials, included in a cURL request:

curl -X POST https://api.test.paysafe.com/alternatepayments/v1/accounts/89987201/payments \
  -u 66040-1001062690:B-qa2-0-579b6aec-0-606c02147caae097f4392898ca08ae736e51d3093af388d90214528ac70b69c0359d3173d12480d07275ca54a7c7 \
  -H 'Content-Type: application/json'

Please note the format to include in your API request as per the above example:

  • 66040-1001062690 – The number sequence before the colon is your user name, to be included in the API endpoint.
  • B-qa2-0-579b6aec-0-… – The number sequence after the colon is your password.
  • The user name and password should be Base64 encoded before being included in your API request. You can do this manually or use a tool to automate this. For more information, see Authentication.
  • 89987201 – Your account number needs to be included in the API endpoint for Card Payments, Direct Debit, 3D Secure, and Alternate Payments API requests.

Make a Payment Request

Below is an example of a simple payment request 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"
    }
  }
}
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"
    }
  ]
}

Troubleshooting API Requests

Below is a brief list of issues that can result in problems.

  • Not sending the request over HTTPS
  • Failure to include the correct authentication details (i.e., your API key) – a common error is adding spaces before or after the API key
  • Incorrect JSON syntax in the body of your request
  • Specifying the incorrect HTTP method – for most API requests this is POST, while requests for retrieving information from the Paysafe platform use GET
  • Forgetting to change the account number (account ID) in the endpoint to your actual account number for those calls that require it
  • Using an account number (account ID) that does not support the request type

For further details, see the Troubleshooting section.

Did you find this page useful?