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 – 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.
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"
}
}
}
{
"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.