Skip to content
ZTLDeveloper Portal

Cross-border payments

Use POST /api/v2/payments/cross-border when your bank account is connected using ZTL. This is different from FX without bank integration.

Build and validate the request

Section titled “Build and validate the request”
  1. Call GET /api/country for supported recipient countries.
  2. Call GET /api/currencies and verify that the payment currency is supported.
  3. Call GET /api/country/{country}/paymentrequirement for the recipient country-specific requirements and build your payment request based on the response.
  4. When regulatory reporting applies, list the applicable codes from GET /api/v2/payments/regulatory-reporting/codes/{countryCode} and present to the sender.
  5. Validate the complete request locally, then handle the validation errors field by field in cases of 400 and 422 responses.

Create, approve, and poll

Section titled “Create, approve, and poll”
  1. Create with POST /api/v2/payments/cross-border and store paymentId.
  2. Present the values from the response to the customer without recomputing them.
  3. Start approval with POST /api/v2/payments/approve, store the approval ID, and present redirect url or QR for SCA.
  4. Complete additional approval if the payment is PartlySigned.
  5. Poll GET /api/v2/payments/approve/{id} and GET /api/v2/payments/{paymentId}/status independently.

When the currency exchange is provided by ZTL, the underlying funding payment must be signed before the returned quote deadline (usually 2 minutes). Do not hard-code that deadline.

If the due date is today, or tomorrow when creating after 16:00, warn the user when the available balance is lower than the payment amount. This reduces the risk of delay or cancellation.

Use the domestic payment status and approval tables for the shared status model.

Cross-border country requirements, regulatory-code lookup, creation, approval, SCA, and status polling

The diagram is supplemental; the ordered steps communicate the same flow.

Payment progress PDF

Section titled “Payment progress PDF”

GET /api/v2/payments/{paymentId}/progress-pdf produces a report only for a cross-border payment with exchange in an eligible state:

API state Report label
InProgress, before ZTL receives funding Scheduled
InProgress, after ZTL receives funding In progress
Completed Sent to bank

The following full-size links show synthetic product-output examples. They are examples of generated reports, not integration flow diagrams.

  • Synthetic payment-progress PDF example showing Scheduled
  • Synthetic payment-progress PDF example showing In progress
  • Synthetic payment-progress PDF example showing Sent to bank

The report communicates the latest known progress; it does not replace API status polling or bank reconciliation.