Authentication

The Merchant API and Partner API use Merchant Credentials or Partner Credentials together with ES256 request signatures for authentication, message-integrity verification, and replay protection. They do not use JWT login sessions.

Integration Credentials

Credential	Purpose
Merchant number	Adopay-assigned merchant identifier, sent in X-Merchant-Id. Partners use their primary merchant number.
P-256 private key	Generated and protected by the merchant or partner; used to create ES256 request signatures.
P-256 public key	Submitted to Adopay during onboarding; used by Adopay to verify request signatures.
Key version	Identified by keyId in Authorization and used for key rotation.

Private keys are server-side credentials. Store them in a secrets manager or controlled environment variable; never place them in client code, logs, or public repositories.

Authentication Headers

All Merchant API and Partner API requests require the following headers:

Header	Description
X-Merchant-Id	Adopay-assigned merchant number; partners send their primary merchant number.
X-Timestamp	Unix timestamp in seconds; the server allows a 300-second clock difference by default.
X-Nonce	Anti-replay nonce; it must not repeat for the same merchant during the validity window.
Digest	SHA-256 digest of the raw request body; hash an empty byte string when the request has no body.
Authorization	ES256 signature information containing the key version, algorithm, signed-header list, and signature value.

See Request Signing for the canonical string, Digest algorithm, code example, and response-verification rules. Business fields are defined by each endpoint.

Authentication Flow

Obtain a merchant number (primary merchant number for partners) and register a P-256 public key
        ↓
Compute Digest and an ES256 signature from the final request
        ↓
Send X-Merchant-Id, X-Timestamp, X-Nonce, Digest, and Authorization
        ↓
Verify Digest and the Authorization signature on the platform response

The gateway always returns HTTP 200. Determine the business result from status in the response body. See Response Status for common gateway response codes.