Platform API
Environments, authentication, and which Tapaya Platform API sections your integration needs.
The Tapaya Platform API lets you manage merchants, payments, and organization settings from your server. Which endpoints you need depends on how your app takes payments; not every integrator needs every section.
Swagger documentationTapaya Integrator APIEvery endpoint, request field, and enum value, with a console to try requests.Open the API reference
Enums are numeric
Fields like businessTypeId, countryId, currencyId, documentType, and refundReasonId are all numeric
enums. The possible values for each are listed in the
Swagger documentation, not in this guide.
Which sections apply to you
| Your integration | Merchant Authentication | Merchant Onboarding | Reporting & Payments |
|---|---|---|---|
| Accept SDK (embedded in your app) | 🟢 Required | 🟡 Optional | 🟡 Optional |
| Tapaya Terminal app only (intent/deeplink, no SDK) | ⚪ Not needed | 🟡 Optional | 🟡 Optional |
| Reporting / back-office only | ⚪ Not needed | ⚪ Not needed | 🟢 Required |
- Merchant Authentication: the SDK authenticates as a merchant using a login token your backend requests. Not needed for Tapaya Terminal integrations: the merchant signs in directly to the Tapaya Terminal app, so there's no SDK session for your backend to authenticate.
- Merchant Onboarding: optional for every payment integration, In-Store or Online. A merchant onboards once and that onboarding covers both channels. Onboard via the Tapaya Platform UI, a hosted invite, or the API, depending on who should collect the merchant's data.
- Reporting & Payments: optional for either payment integration if you build your own dashboards; required (and sufficient on its own) if you're only pulling reporting data with no payment integration of your own.
All rows still require Authentication with a Server Secret Token.
Using the Secret key for Checkout
Online Checkout accepts the same Secret key from the
API Keys page, called a Server Secret Token here.
Checkout requires Authorization: Bearer <secret-key> and resolves the organization to a merchant.
See Checkout authentication for merchant matching requirements.
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.
Authentication
Platform API requests use your Server Secret Token, labelled Secret key on the API Keys page. Pass it as-is in the Authorization header of your HTTP requests.
Authorization: REPLACE_METo authenticate your platform against the API, you must generate a Secret key, referred to here as a Server Secret Token, on the API Keys page and replace REPLACE_ME above with it.
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.
If a token is compromised, revoke it from the API Keys page; revocation takes effect immediately and cannot be undone. Generate a replacement token before or after revoking, as needed; there is no in-place "rotate" action, so update your backend configuration with the new token once it's created.
No key scoping
Every Server Secret Token carries the same organization-wide privileges; tokens cannot currently be scoped to specific endpoints or merchants. Treat any token as equivalent to full API access for your organization.
The server is only accessible through the HTTPS protocol, with TLS 1.2 or later enforced at the infrastructure level. Rate limiting is implemented (100 requests per minute per IP address); requests overloading the server will return a 429 Too Many Requests error.