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.
Swagger Documentation
Explore the full capabilities of the Tapaya API and build your own system on top of it using our Swagger documentation.
Environments
Tapaya Platform API supports the following environments:
- Production: Hosted at
https://api.tapaya.com. This environment uses real accounts and involves real funds. Do not use the production environment for testing. - Sandbox: Hosted at
https://api.sandbox.tapaya.com. This environment allows you to test your integration without any movement of real funds. Learn more about testing in our Testing / Sandbox guide.
Demo mode
The Accept SDK automatically routes requests based on its demo mode setting:
- Demo mode enabled: Connects to the Sandbox environment at
https://api.sandbox.tapaya.com. - Demo mode disabled: Connects to the Production environment at
https://api.tapaya.com.
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_METo authenticate your platform against the API, you must generate a Server Secret Token and replace REPLACE_ME above with it. You can find this token 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 a 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 REPLACE_ME' \
-d '{
"merchantToken": "unique_merchant_id_from_your_db"
}'merchantToken: A unique, stable identifier from your system (e.g., database ID) that identifies the merchant.
Generate Login Token
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 REPLACE_ME' \
-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
Ensure you use the correct merchantToken when retrieving the SDK token. The Tapaya SDK uses this token to log
in on behalf of the merchant, granting 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 REPLACE_ME'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 REPLACE_ME'Add Payment Method
Add an 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 REPLACE_ME' \
-d '{
"paymentMethodId": 1, // 1 = Card, 2 = SEPA, etc.
"onboardingAllowed": true
}'Update Payment Method
Update an 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 REPLACE_ME' \
-d '{
"onboardingAllowed": true
}'Delete Payment Method
Delete an 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 REPLACE_ME'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 REPLACE_ME'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 REPLACE_ME'