API Integration

Learn how to integrate with the Tapaya Platform API to manage merchants and organization settings.

The Tapaya Platform API allows you to manage your integration server-side. While most configuration can be handled via the Tapaya Platform, integrating the Merchant Management endpoints is mandatory to enable your users to log in and use the SDK.

Environments

Tapaya Platform API supports the following environments:

Production environment is hosted at https://api.tapaya.com and uses real accounts involving real funds. Do not use production environment for testing.
Sandbox environment is hosted at https://api.sandbox.tapaya.com and allows you to test the integration without any movement of real funds. Learn more about testing the integration in Testing / Sandbox guide.

Authentication

All API requests must be authenticated using your Bearer token. Pass the token in the Authorization header of your HTTP requests.

Authorization: Bearer REPLACE_ME

To authenticate you platform against API, you have to generate Server Secret Token and replace it with the REPLACE_ME above. You can find in the settings of the Tapaya Platform.

Security Warning

Your Server Secret Token carries high privileges. Never expose it in client-side code (mobile apps, web browsers). It must only be used from your secure backend servers.

The server is only accessible through the HTTPS protocol using TLS 1.2 or later. Rate limiting is implemented, requests overloading the server will return 429 Too Many Requests error.

Mandatory Integration

To allow your merchants to use the Tapaya Accept SDK, you must implement the following endpoints on your backend.

Register a New Merchant

Before a merchant can use the SDK, they must be registered in the Tapaya system. This is typically done when a user signs up for your service. You only need to register the merchant once.

Endpoint: POST /merchant/auth/register

curl -X 'POST' 'https://api.tapaya.com/merchant/auth/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_SERVER_TOKEN' \
-d '{
"merchantToken": "unique_merchant_id_from_your_db"
}'

merchantToken: A unique, stable identifier from your system (e.g., database ID) that identifies the merchant.

To allow a mobile device to initialize the SDK for a specific merchant, you must generate a short-lived login token. Your mobile app will request this from your backend, and your backend will request it from Tapaya. You need a fresh token every time the SDK is initialized.

Endpoint: POST /merchant/auth/login

curl -X 'POST' 'https://api.tapaya.com/merchant/auth/login' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_SERVER_TOKEN' \
-d '{
"merchantToken": "unique_merchant_id_from_your_db"
}'

merchantToken: A unique, stable identifier from your system (e.g., database ID) that identifies the merchant.

Response:

{
  "token": "EesrFq4PUK1WxHUj93hkrKASDFp8GxJ0"
}

Pass this token to your mobile app to initialize the SDK. The token is bound to the merchant identified by merchantToken.

Security Warning

Make sure to use the correct merchantToken when retrieving the SDK token. Tapaya SDK will use the token to login on behalf of the merchant and will have access to their data and funds.

Optional Platform Management

These endpoints provide programmatic access to data and settings that are also available in the Tapaya Platform dashboard. You can use them to build custom dashboards or automate workflows.

List Merchants

List merchants registered under this organization.

Endpoint: GET /platform/integrator/merchant/merchant

curl -X 'GET' 'https://api.tapaya.com/platform/integrator/merchant/merchant' \
-H 'Authorization: Bearer YOUR_SERVER_TOKEN'

List Payment Methods

Retrieve the list of payment methods currently configured for your organization.

Endpoint: GET /platform/integrator/organization/payment-method

curl -X 'GET' 'https://api.tapaya.com/platform/integrator/organization/payment-method' \
-H 'Authorization: Bearer YOUR_SERVER_TOKEN'

Add Payment Method

Add allowed payment method.

Endpoint: POST /platform/integrator/organization/payment-method

curl -X 'POST' 'https://api.tapaya.com/platform/integrator/organization/payment-method' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_SERVER_TOKEN' \
-d '{
"paymentMethodId": 1, // 1 = Card, 2 = SEPA, etc.
"onboardingAllowed": true
}'

Update Payment Method

Update allowed payment method.

Endpoint: PUT /platform/integrator/organization/payment-method/{paymentMethodId}

curl -X 'PUT' 'https://api.tapaya.com/platform/integrator/organization/payment-method/1' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_SERVER_TOKEN' \
-d '{
"onboardingAllowed": true
}'

Delete Payment Method

Delete allowed payment method.

Endpoint: DELETE /platform/integrator/organization/payment-method/{paymentMethodId}

curl -X 'DELETE' 'https://api.tapaya.com/platform/integrator/organization/payment-method/1' \
-H 'Authorization: Bearer YOUR_SERVER_TOKEN'

Retrieve Payment History

Get a list of the latest 50 payments across all merchants in your organization. This is useful for auditing transactions or building a "Super Admin" view.

Endpoint: GET /platform/integrator/organization/payment

curl -X 'GET' 'https://api.tapaya.com/platform/integrator/organization/payment' \
-H 'Authorization: Bearer YOUR_SERVER_TOKEN'

Aggregated Statistics

Get payment statistics aggregated across all merchants in your organization. This endpoint returns total volumes per currency.

Endpoint: GET /platform/integrator/organization/payment/stats

curl -X 'GET' 'https://api.tapaya.com/platform/integrator/organization/payment/stats' \
-H 'Authorization: Bearer YOUR_SERVER_TOKEN'

API Integration

On this page