API Integration

To let your merchants use the Tapaya Accept SDK, your backend registers each merchant and requests a short-lived login token for every SDK session. Both calls use your Server Secret Token; see Platform API authentication to generate one.

Onboarding merchants and pulling payment data work the same for every Tapaya product and are documented in the shared Overview section: Merchant Onboarding API and Reporting & Payments.

Environment routing

The Accept SDK automatically routes requests based on how it was initialized:

Sandbox (default): Connects to the Sandbox environment at https://api.sandbox.tapaya.com.
Production: Connects to the Production environment at https://api.tapaya.com.

Merchant Authentication (Accept SDK integrations)

Accept SDK integrations only

Skip this section if you're driving the Tapaya Terminal app directly (intent/deeplink, no embedded SDK); the signed-in Tapaya Terminal account is the merchant of record, and your backend never authenticates a merchant session. See Integrate without the SDK.

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. Registration can be done in Tapaya Platform UI or using the API.

Endpoint: POST /merchant/auth/register

curl -X 'POST' 'https://api.tapaya.com/merchant/auth/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
        "merchantToken": "unique_merchant_id_from_your_db",
        "merchantName": "Acme Corp",
        "email": "admin@acme.com"
    }'

Parameters:

Field	Type	Required	Description
`merchantToken`	`string`		A unique, stable identifier from your system (e.g., database ID) that identifies
the merchant. If not provided, a random token is generated for you.
`merchantName`	`string`		Human-readable name to identify the merchant in dashboard and reports. Defaults to
`merchantToken` if not provided.
`email`	`string`	✓	Admin email of the merchant, used for login and critical communication.

Responses:

Code	Description
`200`	Merchant successfully registered
`400`	Request validation error
`401`	Unauthorized
`409`	Conflict: merchant already registered

Response body:

{
    "merchantToken": "unique_merchant_id_from_your_db"
}

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: REPLACE_ME' \
-d '{
        "merchantToken": "unique_merchant_id_from_your_db",
        "allowOnboarding": true,
        "employeeEmail": "john@acme.com"
    }'

Parameters:

Field	Type	Required	Description
`merchantToken`	`string`	✓	Integrator's merchant identifier for which the authentication token will be
issued. Same as in `/auth/register`.
`allowOnboarding`	`boolean`		`true` if the user can access and update onboarding/KYB information, enroll new
payment methods, and approve the T&C on behalf of the merchant. Must be `true` for the first call to enable the
merchant to enroll at least one payment method. `false` if the user is denied access to onboarding and can only use
already configured payment methods. Defaults to `true`.
`employeeEmail`	`string`		Email of the employee using the terminal.

Responses:

Code	Description
`200`	Merchant successfully logged in
`400`	Request validation error
`401`	Unauthorized
`404`	Not Found

Response body:

{
    "token": "EesrFq4PUK1WxHUj93hkrKASDFp8GxJ0"
}

Pass this token to your mobile app to initialize the SDK. Securely transport it to the mobile app and delete it immediately after usage. 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.

API Integration

Merchant Authentication (Accept SDK integrations)

Register a New Merchant

Generate Login Token

On this page