# Platform API (/platform-api)





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.

<SwaggerBanner href="https://api.tapaya.com/openapi/index.html" />

<Callout title="Enums are numeric" type="info">
  Fields like `businessTypeId`, `countryId`, `currencyId`, `documentType`, and `refundReasonId` are all numeric
  enums. The possible values for each are listed in the
  [Swagger documentation](https://api.tapaya.com/openapi/index.html), not in this guide.
</Callout>

## Which sections apply to you [#which-sections-apply-to-you]

| Your integration                                                                                                        | [Merchant Authentication](/in-store/integration/backend_integration#merchant-authentication-accept-sdk-integrations) | [Merchant Onboarding](/platform-api/merchant_onboarding) | [Reporting & Payments](/platform-api/reporting) |
| ----------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------: | :---------------------------------------------: |
| **Accept SDK** (embedded in your app)                                                                                   |                                                      🟢 Required                                                     |                        🟡 Optional                       |                   🟡 Optional                   |
| **Tapaya Terminal app only** ([intent/deeplink](/in-store/integration/card_terminal#integrate-without-the-sdk), 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, then track the processor's approval.
* **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](#authentication) with a Server Secret Token.

<Callout title="Using the Secret key for Checkout" type="info">
  [Online Checkout](/online/integration/api_integration#authentication) accepts the same **Secret key** from the
  [API Keys page](https://platform.tapaya.com/api-keys/), called a Server Secret Token here.
  Checkout requires `Authorization: Bearer <secret-key>` and resolves the organization to a merchant.
  See [Checkout authentication](/online/integration/api_integration#authentication) for merchant matching requirements.
</Callout>

## Environments [#environments]

Tapaya Platform API supports the following environments:

* **Production:** Hosted at `https://api.tapaya.com`. This environment uses real accounts and involves real funds. &#x2A;*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](/in-store/getting-started/testing).

## Authentication [#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.

```http
Authorization: REPLACE_ME
```

To 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](https://platform.tapaya.com/api-keys/) and replace *REPLACE\_ME* above with it.

<Callout title="Security Warning" type="warn">
  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.
</Callout>

If a token is compromised, revoke it from the [API Keys page](https://platform.tapaya.com/api-keys/); 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.

<Callout title="No key scoping" type="info">
  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.
</Callout>

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.
