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
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:
error marker {{curlexample}} on page 745
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 (account ID) is typically included in the API endpoint for Card, 3D Secure, Alternate Payments, and Direct Debit API requests.
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.