Skip to main content

Authentication

Last updated: 2026-08-10

The API uses Bearer keys in the HTTP Authorization header:

Authorization: Bearer <key>

There are two key types.

Public key (publishable)​

  • Format: pk_<env>_<base64>
  • Examples: pk_test_..., pk_prod_...

Used only for read-only discovery endpoints:

  • GET /merchant/api/v1/catalog
  • GET /merchant/api/v1/payins/banks
  • GET /merchant/api/v1/payins/mmo
  • GET /merchant/api/v1/payouts/banks
  • GET /merchant/api/v1/payouts/mmo

Start with GET /merchant/api/v1/catalog to retrieve the countries, currencies, and method families enabled for your account. Then use the bank and operator discovery endpoints with the same request context you will use for the selected payment flow.

Secret key​

  • Format: sk_<env>_<base64>
  • Examples: sk_test_..., sk_prod_...

Used for all other endpoints: payment creation and initialization, OTP authorization, payment reads, and balances. New balance integrations use GET /merchant/api/v2/balances and GET /merchant/api/v2/balances/history.

Live and sandbox realms​

All requests use https://merchants-api.tcpay.io. The key suffix selects the financial realm used by the request:

  • *_test_* keys access the merchant's sandbox realm.
  • *_prod_* keys access the merchant's live realm.

There is no separate development URL. Use the same base URL and the key set for the realm you intend to access.

Keep sandbox and live records separate in your integration. Catalog results, payments, balances, and webhook deliveries belong to the scope selected by the key used for that request.

Rotate credentials in the Merchant Portal​

Authorized users can rotate the publishable and secret key pair for the selected realm in the Merchant Portal.

  • Rotation is an immediate cutover: the previous pair stops working when the rotation succeeds.
  • Copy the new secret key when it is shown and store it securely; the portal does not provide it as a permanently viewable value.
  • Update every caller that uses the rotated realm before resuming traffic.
  • Rotation also changes the webhook signing secret for that realm. Update your verifier at the same cutover.