Getting started
The Abbreviations, Endpoint, Security and JSON Web Tokens sections below are shared across every API in this reference — each API page's own Endpoint line links back here for the server URL, authentication and JSON Web Tokens.
Abbreviations
- Y — Compulsory
- O — Optional
- CY — conditional requirement
- CO — appears in the parameter tables (used in avs.md and debit-order.md) but is not defined in the source documentation; its meaning is being confirmed
- N — appears in the parameter tables throughout payments.md but is not defined in the source documentation; its meaning is being confirmed
Endpoint
| API | Endpoint |
|---|---|
| Payments | {server}/api/payments/v2/ |
| Debit Order | {server}/api/collections/v1/ |
| AVS | {server}/api/avs/v1/ |
| Wallet | {server}/api/wallet/v1/ |
| Webhook | see Webhooks |
Notes:
- The
{server}URL is the same as your portal login. - Append each function onto the endpoint.
Security
Each API call requires a JSON Web Token comprising of the following:
- apiKey: Provided by customer support
- accessToken: provided by customer support
- jti: A unique JWT ID (Unique means it is different for each call)
- iat: Issued at time
- exp: Expiry time – a future time when the token is no longer valid
The token should be signed with the secret setup on your console login. Signing can be done with any of the HMAC algorithms.
Example token payload structure:
{
"apiKey": "{PROVIDED API KEY}",
"accessToken": "{PROVIDED ACCESS TOKEN}",
"jti": "{UNIQUE VALUE}",
"iat": 1589990902,
"exp": 1589991502
}
Your API Key and Access tokens are available in the console under Setup > General Settings > API Settings. Or request these from customer support.
Your JWT Secret, Origin domain or IP, post-back URL, and post-back content-type can all be set in the console under Setup – General Settings – API Settings and selecting the corresponding token. Or send these to customer support for updating.
Once testing is complete the calling Origin should be locked in to prevent API calls from unauthorised origins or IPs. You can specify your Origin as part of your HTTP Header. If this is not set your server IP can be used.
JSON Web Tokens
For more information on JWTs and libraries for your development language see jwt.io.