Making API Calls
Before you make your first API call, you will need to have some or all of the following information at hand:
- API endpoint – This is the URI to which you send your request, and its format depends on the type of API call.
- API key – You obtain this when you sign up for a Test account and get access to the Paysafe Back Office, and must include it in the Authorization HTTPS header of most API requests. Once logged in to the Back Office, choose Settings > API Key and make a note of your API Key User name and Password; the password is also available Base64 encoded.
- Account number – Some API calls require an account number (Account ID), where it is included either in the API endpoint (e.g., Card Payments, 3D Secure 2, and Direct Debit) or in the body of the request (e.g., Hosted, extendedOptions). You obtain this when you sign up for a Test account and get access to the Paysafe Back Office; once logged in, choose Accounts and then copy your account number from the Account column.
- Message body – This must be valid JSON and contain valid Paysafe JSON objects as required for the type of request. Not all API calls require a message body – for example, GET requests do not require a body.
- Resource ID – Some API calls require a resource ID in the API endpoint, for example, to refer to a resource that has been created in a previous step.
Structure of a Typical API Request
Your API call typically requires you to include the following credentials :
|API Key||Your API key is a concatenation of your user name and password, separated by a colon. The key must also be Base64 encoded. For details of where to find this, click here.|| |
Your API key credentials (user name and password located in the Settings > API Key section of the Merchant Back Office) are not the same as the username and password you use to sign in to the Merchant Back Office.
Each account you create is set up with a unique API key, but you can request to have the same API key set up for all your accounts.
The code snippet below provides an example of the above credentials, included in a cURL request:
curl -X POST https://api.test.paysafe.com/threedsecure/v2/accounts/89987201/authentications \
-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 typically needs to be included in the API endpoint for Card, 3D Secure, Alternate Payment Methods, and Direct Debit API requests.
Where a transaction currency is specified in the body of the request, this must be the same as the currency linked to the account number specified in the API endpoint.
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
- The currency specified in the request is not the same as the currency of the account specified in the API endpoint
For further details, see the Troubleshooting section.