Overview

ZTL OpenAPI v2.0

ZTL API

The ZTL API supports authentication, company onboarding, bank consent, account information, domestic and cross-border payments, payroll, companies, FX, currencies, and country requirements.

Download this exact contract at https://docs.ztlpay.io/ztl-api-v2.full.yaml.

Partner journey

Obtain credentials and fetch an access token.
Onboard the company and poll until its status is Accepted.
Create bank consent and let the user complete SCA.
Retrieve and store the authorized accounts.
Create a payment or payroll.
Start the separate approval phase and let the user complete SCA.
Poll the resource until every transaction reaches a final state.

Request headers

Most responses include ztl-request-id. Log it with the relevant resource identifier so ZTL support can trace an operation.

Some endpoints use PSU-IP-Address and PSU-User-Agent to state that the end user is actively present. Forward only values observed from the current user session. Never fabricate them, send your server’s values, or replay stored values.

Errors and compatibility

Check the HTTP status and then parse the structured failure body defined by the operation. Capture ztl-request-id from the header and body when present. New failure codes and status enum values can be added, so clients must preserve and safely handle unknown values.

Reconcile ambiguous create or approval outcomes through stored resource IDs, partner references, status operations, and request IDs before sending another request.

Environments

Resource	Sandbox	Production
API	`https://api.sandbox.ztlpay-test.io`	`https://api.ztlpay.io`
Authentication	`https://oidc.sandbox.ztlpay-test.io`	`https://oidc.ztlpay.io`
Onboarding	`https://welcome.sandbox.ztlpay-test.io/onboarding`	`https://welcome.ztlpay.io/onboarding`

Supported banks, countries, currencies, and partner enablement must be read from the relevant API and confirmed with ZTL for the target environment.

Workflow guides

Information

OpenAPI version: 3.1.0

Authentication

OAuth2Sandbox

Use with the Sandbox API server only.

Security scheme type: oauth2

Flow type: clientCredentials

Token URL: https://oidc.sandbox.ztlpay-test.io/v2/connect/token

Scopes:

api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - Access the ZTL Sandbox API.

OAuth2Production

Use with the Production API server only.