Keys and configuration

Updated: 2026-08-21 01:32

Key types

Key	Used by	Purpose
API Key	Merchant calls the API service	Identifies the merchant, credential and product permission. Source access is controlled by the platform operations security group.
API Secret	Merchant backend only	Calculates the HMAC-SHA256 request signature. Never send it to the API service.
Webhook Secret	Merchant webhook receiver	Verifies Webhook deliveries sent by the platform. It is selected by Webhook-Secret-Id.

The API Key is not a login token. It is a credential identifier bound to a merchant number and permission scope. The API Secret is the shared secret used to prove that the caller controls that credential.

Relationship model

A merchant has at most one primary and one replacement API Key in each environment. Each Key has one current API Secret. The replacement slot exists so the merchant can deploy and verify a new Key while the primary Key is still in use, then revoke the old Key without downtime.

API credentials and Webhook endpoints are independent resources. Creating a Webhook does not require an API Key, and enabling, disabling or revoking a Key does not change Webhook delivery. A merchant can create multiple endpoints. Each endpoint has one HTTPS URL, one current Webhook Secret and one or more subscribed event types. The same event type can be delivered to multiple endpoints.

Merchant Portal shows the current Webhook Secret and Webhook Secret ID for 60 seconds after endpoint creation or Secret rotation. The receiver must store the mapping, for example:

Webhook-Secret-Id=whsecid_endpoint_a -> whsec_endpoint_a
Webhook-Secret-Id=whsecid_endpoint_b -> whsec_endpoint_b

The receiver selects the Secret by Webhook-Secret-Id and verifies Signature before processing the event. It must keep historical mappings for as long as an automatic delivery can still use the Secret saved for an older endpoint version.

Create credentials

Create credentials in Merchant Portal under International Payments API access. The API Secret is shown only once in the current page session after creation. It can be copied again from that page until the operator confirms it was saved; after a browser refresh or close, it cannot be viewed or recovered. Store it immediately in a server-side secret manager such as Vault, KMS or a controlled environment variable store.

Create Webhook endpoints under Webhooks and select the events for each endpoint. New endpoints are disabled by default. Endpoint creation is not part of API Key creation and does not change API authentication status.

Do not put API Secrets or Webhook Secrets in frontend code, mobile apps, repositories, logs, monitoring screenshots or support tickets.

Enablement checks

A live-mode API Key should stay disabled until these API checks pass:

• Merchant onboarding and product authorization are complete.
• Country, currency, product, fee and settlement account are enabled.
• Fixed outbound IP addresses are approved by platform operations at the gateway security group, WAF or API Gateway. API credentials contain no IP field.
• Request signing test vectors pass with the production signing code.

Webhook enablement is a separate decision. Enable an endpoint only after its subscriptions are correct and its receiver can durably accept signed events. The receiver should return HTTP 200 OK; the platform treats any 2xx as successful receipt.

Rotation

For routine API Key or API Secret rotation, create a replacement API Key and run old and new Keys in parallel for a short cutover window. Confirm cutover by checking the latest usage time, disable the old Key for an observation period, then revoke it permanently. Do not keep replacement Keys permanently active unless they belong to different backend systems or permission scopes.

If an API Secret is unavailable to the operator, the platform cannot show or recover that Secret again. Create a replacement Key, cut traffic over to it, and then revoke the old Key. Use the same replacement flow if exposure is suspected.

For Webhook endpoint rotation, create a separate replacement endpoint, select the same intended events, deploy and enable its receiver, then disable the old endpoint. During overlap, one event is delivered to both endpoints. Updating an endpoint URL disables it and marks pending deliveries as skipped until the new receiver has been reviewed and the endpoint is enabled again.

For Webhook Secret rotation, first disable the endpoint. Merchant Portal creates a new Webhook Secret ID and version and shows the current Secret for 60 seconds. Automatic retries already created before the rotation continue with the URL and Secret version saved at that time; a manual replay uses the endpoint's current URL and current Secret. Keep the old Secret-ID mapping in the receiver through the automatic retry window, then remove it from the merchant secret manager.

Continue with signing and verification and Webhook introduction and configuration.