Version: 1.1 · Updated: 2026-10-03
1. Scope and ownership
Merchant means a business registered with DLT. This guide covers authentication by that business's own server integration, such as the backend of its website or mobile application. DLT Merchant Portal is DLT's own ecosystem frontend and has a separate Portal API guide.
A merchant-owned integration client is bound to one registered business. Its credentials authenticate the integration server, with no human user attached to the issued machine token. Keep the secret and machine token on that server, outside browser bundles and mobile applications.
2. Obtain a machine access token
Obtain a client ID and secret issued for your registered business. An authorized Merchant Administrator can manage these through DLT Merchant Portal's account settings; DLT staff can also provision merchant machine access. Store the credentials on your integration server.
POST /oauth/token
Accept: application/json
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=<url_encoded_client_id>&client_secret=<url_encoded_client_secret>&scope=
URL-encode each form value. An empty scope is appropriate for existing collection routes that use the client middleware without a route-specific scope. Do not invent unregistered scope names.
2.1 Request validation: POST /oauth/token
Send application/x-www-form-urlencoded from the merchant integration server. These rules come from the installed Passport/League OAuth server; this route uses OAuth errors rather than Portal field errors.
| Field | Location | Requirement | Validation rules |
|---|---|---|---|
grant_type |
Form body | Required | Exactly client_credentials for this flow. Missing/unrecognized grant types cannot select this grant. |
client_id |
Form body | Required in this example | Issued client identifier; must resolve to an active, unrevoked confidential Passport client allowed to use this grant. Use the issued value as text; do not invent a numeric-only or UUID-only rule. |
client_secret |
Form body | Required for this confidential client | String containing the issued plaintext secret; must match the stored secret. A database hash is not a usable secret. No application-level minimum/maximum length rule is imposed by this grant. |
scope |
Form body | Optional | Space-separated registered scope identifiers. Empty scope requests no explicit scopes; omission uses the configured default. Unknown scopes fail with invalid_scope. Do not send arbitrary Portal role names as scopes. |
Passport also accepts client credentials through HTTP Basic authentication when those form fields are omitted. The example deliberately supplies them in the form; do not supply conflicting credentials through both locations. This grant does not use username, password, a user token, password_confirmation or X-DLT-Application. Unrelated body parameters are not rejected as unknown fields by this grant and do not become token claims. Do not rely on ignored fields to set a merchant, user, lifetime or environment.
| Validation outcome | Response behavior |
|---|---|
| Missing client identifier or invalid parameter type | OAuth invalid_request (400) |
| Unsupported/missing grant type | OAuth unsupported_grant_type (400) |
| Invalid/revoked/nonconfidential client or incorrect/missing secret | OAuth invalid_client (401) |
| Unknown scope | OAuth invalid_scope (400) |
Merchant ownership, business activation and rotation-deadline eligibility are enforced on merchant API calls. A successful token grant does not prove those checks passed. The exact OAuth error description is feedback; use the error code and status. For example, an unknown scope returns an OAuth error body containing:
{
"error": "invalid_scope",
"error_description": "The requested scope is invalid, unknown, or malformed"
}
Passport returns an OAuth response, without the application's success/data envelope:
{
"token_type": "Bearer",
"expires_in": 31536000,
"access_token": "<machine_access_token>"
}
expires_in is illustrative. Use the returned lifetime, cache the token on the merchant server and repeat the grant before expiry. Do not assume a fixed lifetime from this example.
Machine tokens authenticate merchant integration APIs, not Portal user endpoints.
3. Call merchant integration APIs
Use the issued token on the merchant API endpoint documented for your enabled service:
Authorization: Bearer <machine_access_token>
Accept: application/json
Use the endpoint-specific request format. DLT validates the token, client ownership, active business and required scopes. This guide covers server authentication only; it does not define a payment submission or webhook API contract. Obtain the applicable service API contract from DLT.
4. Renewal, rotation and errors
Cache the token server-side and repeat the client credentials grant before its returned expiry. Use replacement credentials before the previous client's rotation deadline. A token grant alone does not prove that an integration client remains eligible: after its ownership deadline, merchant APIs reject it even if Passport can still issue a token. Explicit client revocation also invalidates its tokens.
| Result | Integration handling |
|---|---|
| OAuth token error | Parse the OAuth error response; check credentials and grant parameters |
| 401 on an API call | Check token expiry/revocation; obtain a new token only while the client remains valid |
403 CLIENT_MERCHANT_NOT_AUTHORIZED |
Client ownership or business eligibility failed; correct provisioning rather than repeating the grant |
403 INSUFFICIENT_SCOPE |
The API requires a scope absent from the token |
403 MERCHANT_SCOPE_MISMATCH |
A supplied merchant identifier conflicts with the authenticated business |
503 MERCHANT_MACHINE_API_UNAVAILABLE |
Machine API access is disabled for the deployment |
| 429 | Respect the endpoint throttle and any Retry-After header |
/oauth/token has Passport's throttle and OAuth response format. Do not parse its success response using the Portal success/data envelope. Do not use Portal user sessions or the Portal ecosystem application secret for this grant.
5. Other merchant integration assets
Some existing web integrations have authentication_token and secret_key assets. These are distinct from OAuth client credentials. The current secret_key is used for payment notification signing, with the existing x_token fallback where configured. Coordinate webhook verifier changes with key rotation: queued notifications may retain an earlier signing key. Removing the key without a fallback can prevent future notifications. Use the service-specific webhook contract for verification instructions.
The authentication_token field maps to the legacy auth_token asset; this checkout does not establish an active runtime consumer for it. Do not treat it as a general-purpose API bearer token. Provider credentials are managed separately by DLT.