Getting Started

Before starting integrate our API, please make sure you have a commercial agreement with us and get in touch with your Integrate Support Team.

Basic workflow：

1. Read the API document
2. Integrating and developing in a sandbox environment
3. Open a live account
4. Start making transactions

Connect to our API

Obtaining your API key

An API key is a unique alphanumeric string of 64-bit length used to authenticate and authorize access to our API services. It's like a key that grants you access to specific resources and functionalities of our API.

Before integrating with our API, ensure you've signed a commercial agreement and completed the KYB process. Our Integration Support team will assist you with KYB process and generate your apiUser. You'll need to provide an email address additionally.

Please complete these steps before requesting API access. The apiUser and email address are mandatory parameters for API key generation.

Use the correct URL

There are two separate environments available throughout the integration process: Sandbox and Production. Although the authentication method is the same across both environments, ensure you use the correct base URLs:

Sandbox

The sandbox environment is where you'll initially integrate with Capay OpenAPI. This environment should be used to finalise your workflow, test your integration, and make sure no test data is shared with the production environment.

Production

The production environment is where the actual business operations take place with Capay OpenAPI. This environment will be used once your testing is complete and you are ready to make transactions with real money.

Calling our API

After receiving your API key, get the access token using your apiUser and apiKey. For authentication, include the access token in the Authorization header of each API request.

curl --location --globoff '{{APIDOMAIN}}/beneficiaries/businesses?skip=0&limit=10' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}'

Example of an authorization request:

{
"apiUser": "{{API_USER}}", "apiKey": "{{API_KEY}}"
}

Example of 200 success response containing the access token and expiry:

{
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImVkNDYyNzFmLTFkNjItNDQ3NC1iY2QzLWQyNTdhZDFmOWM4NSIsImFwaVVzZXIiOiJhcGl1c2VyQGFscGhhLmNvbS5hdSIsImFwaUtleSI6ImE3ODhmZWFjODQzMzRlYmQ4OWMzMGUzMmQyNmFkNmI3YjYwMjM2Y2ZlNDYyNDNmZTk4ZThiNTNjYjEyZWQwNTUiLCJ0ZW5hbnRJZCI6IjJmMWY2NjhiLTViN2MtNGNiMy04NDgzLTIwMjYxOTEyOWZhMSIsImNvbXBhbnlJZCI6IjNmZmUxYTRhLWM2NzctNDc1OS1hNzk4LTRiY2NiMGFmOTAxNSIsImNvbXBhbnlUeXBlIjoxLCJpYXQiOjE3MzQzMzg5ODcsImV4cCI6MTczNDM0MjU4N30.EihdtqzsOLMgIP7iBPbhXcgWh0Ez_fg8ftu0F0YXinU",
    "expiresInSeconds": 3600
}

note

Tokens expire after 60 minutes.

Webhook events

We will send you a notification every time the ticket status changes. To receive webhook events, first create a Webhook for your OAuth application and connect the target OAuth-authorized account to it.

User persona

CAPAY OpenAPI supports two types of users: PM (Program Manager) and Client. For more details, please refer to Understanding User Persona

About our API

API security

We use standard JWT OAuth 2.0 signed token. Our tokens contain the access rights of the user requesting access. You need put api user, and api key to our Authorization endpoint. Access tokens expire after 1 hour.

Encryption

All Capay OpenAPIs enforce mutual TLS 1.3.

Error handling

The API uses HTTP response codes for requests: 2xx codes for success, 4xx codes for endpoint specific errors concerning e.g. permissions, missing parameters or other failure(s), data errors and 5xx codes for internal server errors.

HTTP code	Meaning	Description
200	OK	Request has been processed with success
201	Created	New resource has been created
400	Bad request	Request is not correctly formulated. Goes for both Header, Query and Body. Verify the error description and properties.
401	Unauthorized	The request requires user authentication.
403	Forbidden	The server understood the request, but is refusing it or the access is not allowed, i.e. if resource exists but calling user does not have rights to access it.
404	Not found	There is no resource behind the URL, i.e. requesting data on an account that does not exist
500	Internal server error	Something unexpected happened on our side