ZTL API Documentation - Back to main docs

ZTL OpenAPI (v1.0)

Download OpenAPI specification:Download

Ztl Payment solution api

You can download the full spec on the button above or at https://docs.ztlpay.io/ztl-api.full.yaml

General

  • All responses contains a header called Ztl-Request-Id. This is our reference for the operation performed and you should at least log these to enable better tracing and debugging.
  • Error handling follows HTTP error codes as closely as possible
  • Please take extra care to handle 5xx and avoid getting the user to try again immediately. While we try to make sure 503s are in fact temporary; some times it is related to longer downtimes.

Authentication

oAuth Authentication

Fetch an access token

Request Body schema: application/x-www-form-urlencoded
client_id
required
string
client_secret
required
string
grant_type
required
string
scope
required
string

Responses

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IkE1NEZCQjFGRjgzRTZFRUFEQUI1MTg4QTJBMkVGRDhGNTUzMEUzNDkiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJwVS03SF9nLWJ1cmF0UmlLS2k3OWoxVXc0MGsifQ.eyJuYmYiOjE1NjI4MzE1OTIsImV4cCI6MTU2MjgzNTE5MiwiaXNzIjoiaHR0cHM6Ly9vaWRjLnp0bC5zdGFjY2Zsb3cubmV0IiwiYXVkIjpbImh0dHBzOi8vb2lkYy56dGwuc3RhY2NmbG93Lm5ldC9yZXNvdXJjZXMiLCJ6dGwtYXBpIiwicG9ydGFsLWFwaSJdLCJjbGllbnRfaWQiOiJkZXZjbGllbnQiLCJzY29wZSI6WyJwYXltZW50cyIsInBvcnRhbC1hcGkiXX0.dJuDJNTsSBhQ_xmN3ruqbBZvJdyn2nUkUW3NEwbgXw_l-UA3_XRmtp16rWWdhMLbh-D_HywwG2a0h-MK2tX17C-ggsfp_pDxj8iy8aLleI3dY1qt0VkQY8rOw5_YtWa40HWwIBK9Ll8MqovwBK4lg9Pkq_KLGdkoz87n63QezS5u0JeWYJJnHFuY5ojX_M5szAdSYoVYOyvL0tr30ynxb3joglKrVWlkeawRZztRV4chFN00tlv_Tn54vDYOyDPtBWK6JpMVqhHla8a5JnslJu5dUP82qtgms_lFYOiR1oD2jaa-t0QTE6MVwspG3kwQBSSSZawe-9G4yEBg-nFSGg",
  • "expires_in": 3600,
  • "token_type": "Bearer"
}

Onboarding

Onboarding

Start an onboarding

Authorizations:
Authorization
Request Body schema: application/json
organizationId
required
string
webhookUrl
string
redirectUrl
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Get onboarding status and information

Authorizations:
Authorization
path Parameters
flowId
required
string

Onboarding flowId, returned after initiating an onboarding.

Responses

Response samples

Content type
application/json
{
  • "orgName": "Ztl",
  • "orgNo": "12345678",
  • "status": "completed",
  • "tasks": [ ],
  • "redirectUrl": "https://example.org",
  • "webhookStatuses": {
    }
}

Delete an onboarding

Authorizations:
Authorization
path Parameters
flowId
required
string

Onboarding flowId, returned after initiating an onboarding.

Responses

Response samples

Content type
application/json
{
  • "code": "SYSTEM_ERROR",
  • "message": "Server error"
}

Consent

Manage the End User Consent (SCA)

Check status of the consent

Authorizations:
Authorization
query Parameters
consentAuthorizationId
required
string

Consent Authorization Id

Responses

Response samples

Content type
application/json
{
  • "reason": "string",
  • "status": "string",
  • "authorizationType": "SINGLE_AIS,RECURRING_AIS",
  • "consentState": {
    },
  • "expirationDate": "2019-08-24T14:15:22Z"
}

Create consent

Authorizations:
Authorization
header Parameters
Idempotency-Key
required
string <UUID>
Example: 49ae0cfe-6b72-4310-81f5-ad4eef897fe3

Unique identifier for idempotency

PSU-IP-Address
required
string <ipv4>
Example: 192.158.1.38

AAA IP Address of the end-user initiating the payment. DO NOT use any other IP address than what you can collect from the current user session that uses your system (don't use something stored in your DB). This information is used by the banks to manage traffic and handle security. Mandatory in all calls in Sweden.

Request Body schema: application/json
required

Consent request object

callbackUrl
required
string^(http|https)://.*$

Sca callback url can be configured here

accountOwnerSsn
required
string

Private identification number

accountOwnerOrganizationReference
required
string

Corporate ID required for corporate consent creation at ASPSP.

debtorBankBic
required
string

Bic to identify the bank

instructionId
required
string <= 36 characters

Instruction id

Responses

Request samples

Content type
application/json
{
  • "callbackUrl": "string",
  • "accountOwnerSsn": "string",
  • "accountOwnerOrganizationReference": "string",
  • "debtorBankBic": "string",
  • "instructionId": "string"
}

Response samples

Content type
application/json
{
  • "scaUrl": "string",
  • "consentAuthorizationId": "string",
  • "status": "string",
  • "reason": "string",
  • "expirationDate": "2019-08-24T14:15:22Z"
}

Revoke Consent

Authorizations:
Authorization
header Parameters
Consent-Reference
required
string <UUID>
Example: b0fc2430-3d87-470d-83f5-a4e94d540f6f

Consent Reference to be revoked

Responses

Response samples

Content type
application/problem+json
{
  • "type": "urn:input-validation-failed",
  • "title": "Bad Request",
  • "detail": "Missing required header Consent-Reference"
}

Accounts

APIs available for doing the AISP operations

Account Balance

Retrieve the current available and booked balance for the account or accounts specified in the authorized query.

Authorizations:
Authorization
path Parameters
accountId
required
string

The ID of the account, as retrieved from the list of accounts. The account ID is sometimes the same as the account bban, but this is not always the case. Also, the account ID may change each time a consent is created/refreshed.

query Parameters
consentAuthorizationId
required
string

The Consent Authorization Id, as retrieved from the Create Consent-request.

consentReference
required
string <uuid>
Example: consentReference=b0fc2430-3d87-470d-83f5-a4e94d540f6f

The Consent Reference, as retrieved from the Create Consent-request.

header Parameters
PSU-IP-Address
string <ipv4>
Example: 192.158.1.38

AAA IP Address of the end-user initiating the payment. DO NOT use any other IP address than what you can collect from the current user session that uses your system (don't use something stored in your DB). This information is used by the banks to manage traffic and handle security. Mandatory in all calls in Sweden.

PSU-User-Agent
string

PSU-User-Agent - The forwarded Agent header field of the HTTP request between PSU and TPP, if available. Example: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:54.0)

PSU-Geo-Location
string

PSU-Geo-Location - The forwarded Geo Location of the corresponding HTTP request between PSU and TPP if available. Example: GEO:52.506931;13.144558

Responses

Response samples

Content type
application/json
{
  • "id": "22cc5740-f8f5-1234-abcd-b90e42531234",
  • "name": "Spending account",
  • "bic": "DNBANOKK",
  • "bban": 12043175449,
  • "iban": "NO0812043175449",
  • "country": "NO",
  • "type": "Debit",
  • "currency": "NOK",
  • "balance": {
    }
}

Account Entries

Retrieve the latest transaction entries on the account or accounts specified in the authorized query.

Authorizations:
Authorization
path Parameters
accountId
required
string

The ID of the account, as retrieved from the list of accounts. The account ID is sometimes the same as the account bban, but this is not always the case. Also, the account ID may change each time a consent is created/refreshed.

query Parameters
consentAuthorizationId
required
string

The Consent Authorization Id, as retrieved from the Create Consent-request.

consentReference
required
string <uuid>
Example: consentReference=b0fc2430-3d87-470d-83f5-a4e94d540f6f

Consent Reference

fromDate
string <date, ISO-8601>
Example: fromDate=2022-01-01

Entries start date, inclusive

toDate
string <date, ISO-8601>
Example: toDate=2022-01-02

Entries end date, inclusive

header Parameters
PSU-IP-Address
string <ipv4>
Example: 192.158.1.38

AAA IP Address of the end-user initiating the payment. DO NOT use any other IP address than what you can collect from the current user session that uses your system (don't use something stored in your DB). This information is used by the banks to manage traffic and handle security. Mandatory in all calls in Sweden.

PSU-User-Agent
string

PSU-User-Agent - The forwarded Agent header field of the HTTP request between PSU and TPP, if available. Example: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:54.0)

PSU-Geo-Location
string

PSU-Geo-Location - The forwarded Geo Location of the corresponding HTTP request between PSU and TPP if available. Example: GEO:52.506931;13.144558

Responses

Response samples

Content type
application/json
{
  • "account": {
    },
  • "accountEntries": [
    ]
}

Entry details

Obtain detailed information about a specific transaction by utilizing the unique transactionId, which is accessible through the entries endpoint. For a complete set of details, use this endpoint in conjunction with the entries endpoint.

Authorizations:
Authorization
path Parameters
accountId
required
string

The ID of the account, as retrieved from the list of accounts. The account ID is sometimes the same as the account bban, but this is not always the case. Also, the account ID may change each time a consent is created/refreshed.

transactionId
required
string

The ID of the transaction, as retrieved from the list of entries.

query Parameters
consentAuthorizationId
required
string

The Consent Authorization Id, as retrieved from the Create Consent-request.

consentReference
required
string <uuid>
Example: consentReference=b0fc2430-3d87-470d-83f5-a4e94d540f6f

Consent Reference

header Parameters
PSU-IP-Address
string <ipv4>
Example: 192.158.1.38

AAA IP Address of the end-user initiating the payment. DO NOT use any other IP address than what you can collect from the current user session that uses your system (don't use something stored in your DB). This information is used by the banks to manage traffic and handle security. Mandatory in all calls in Sweden.

PSU-User-Agent
string

PSU-User-Agent - The forwarded Agent header field of the HTTP request between PSU and TPP, if available. Example: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:54.0)

PSU-Geo-Location
string

PSU-Geo-Location - The forwarded Geo Location of the corresponding HTTP request between PSU and TPP if available. Example: GEO:52.506931;13.144558

Responses

Response samples

Content type
application/json
{
  • "transactionId": "d1f669f2-1234-abcd-aabb-ff0cc229b485",
  • "postedAmount": {
    },
  • "type": "Debit",
  • "status": "Pending",
  • "bookingDateTime": "2022-01-02",
  • "valueDateTime": "2022-01-01",
  • "purposeText": "Overføring Innland",
  • "remittanceInformation": {
    },
  • "creditor": {
    },
  • "debtor": {
    },
  • "endToEndId": "string"
}

List of Accounts

Retrieve a list and general information about the account or accounts specified in the authorized account query. Note that this information can only be fetched during 1 hour after created consent.

Authorizations:
Authorization
query Parameters
consentAuthorizationId
required
string

Consent Authorization Id

consentReference
required
string <uuid>
Example: consentReference=b0fc2430-3d87-470d-83f5-a4e94d540f6f

Consent Reference

withBalance
boolean

With Balance - Whether or not balance information should be added to the account details.

withCard
boolean

With Card - Whether or not card information should be added to the multiple accounts

header Parameters
PSU-IP-Address
string <ipv4>
Example: 192.158.1.38

AAA IP Address of the end-user initiating the payment. DO NOT use any other IP address than what you can collect from the current user session that uses your system (don't use something stored in your DB). This information is used by the banks to manage traffic and handle security. Mandatory in all calls in Sweden.

PSU-User-Agent
string

PSU-User-Agent - The forwarded Agent header field of the HTTP request between PSU and TPP, if available. Example: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:54.0)

PSU-Geo-Location
string

PSU-Geo-Location - The forwarded Geo Location of the corresponding HTTP request between PSU and TPP if available. Example: GEO:52.506931;13.144558

Responses

Response samples

Content type
application/json
{
  • "accounts": [
    ]
}

Payments

Payments

Initiate a payment

Authorizations:
Authorization
header Parameters
PSU-IP-Address
required
string <ipv4>
Example: 192.158.1.38

AAA IP Address of the end-user initiating the payment. DO NOT use any other IP address than what you can collect from the current user session that uses your system (don't use something stored in your DB). This information is used by the banks to manage traffic and handle security. Mandatory in all calls in Sweden.

PSU-Geo-Location
string

Geo Location of the one initiating the payment

PSU-User-Agent
string

User agent of the one initiating the payment

Request Body schema: application/json
idempotencyKey
required
string <uuid>

Unique identifier for the payment request. This could also be used as a query parameter in the scaRedirectUrl for identifying the payment when the user returns from SCA.

organizationId
required
string

The organization number of the debtor

countryCode
required
string <ISO 3166-1 alpha-2>

Country code for the organization

consentReference
required
string

The consent reference given when creating a consent.

scaRedirectUrl
required
string

The url the user is redirected to after confirming payment with SCA

base64Pain001
required
string <iso20022 Payment initiation v03 (PAIN)>

Encoded in base64. See https://docs.ztlpay.io/#initiate-payment for details.

Responses

Request samples

Content type
application/json
{
  • "idempotencyKey": "123123-123-12-2222",
  • "countryCode": "NO",
  • "organizationId": "123456789",
  • "scaRedirectUrl": "https://example.com/callback",
  • "consentReference": "123123-123123-123123-2",
  • "base64Pain001": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiP...mZJbml0bj4NCjwvRG9jdW1lbnQ+DQo="
}

Response samples

Content type
application/json
{}

Validate a payment

Authorizations:
Authorization
header Parameters
PSU-IP-Address
required
string <ipv4>
Example: 192.158.1.38

AAA IP Address of the end-user initiating the payment. DO NOT use any other IP address than what you can collect from the current user session that uses your system (don't use something stored in your DB). This information is used by the banks to manage traffic and handle security. Mandatory in all calls in Sweden.

PSU-Geo-Location
string

Geo Location of the one initiating the payment

PSU-User-Agent
string

User agent of the one initiating the payment

Request Body schema: application/json
idempotencyKey
required
string <uuid>

Unique identifier for the payment request. This could also be used as a query parameter in the scaRedirectUrl for identifying the payment when the user returns from SCA.

organizationId
required
string

The organization number of the debtor

countryCode
required
string <ISO 3166-1 alpha-2>

Country code for the organization

consentReference
required
string

The consent reference given when creating a consent.

scaRedirectUrl
required
string

The url the user is redirected to after confirming payment with SCA

base64Pain001
required
string <iso20022 Payment initiation v03 (PAIN)>

Encoded in base64. See https://docs.ztlpay.io/#initiate-payment for details.

Responses

Request samples

Content type
application/json
{
  • "idempotencyKey": "123123-123-12-2222",
  • "countryCode": "NO",
  • "organizationId": "123456789",
  • "scaRedirectUrl": "https://example.com/callback",
  • "consentReference": "123123-123123-123123-2",
  • "base64Pain001": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiP...mZJbml0bj4NCjwvRG9jdW1lbnQ+DQo="
}

Response samples

Content type
application/json
{
  • "type": "urn:pain-invalid",
  • "title": "Invalid Pain",
  • "detail": "There are 2 errors",
  • "detail2": "",
  • "errors": [
    ],
  • "traceId": "03f55df4-d7d7-416a-add6-0f427eec7f92"
}

Get payment information

Authorizations:
Authorization
path Parameters
flowId
required
string <uuid>

Payment ID

Responses

Response samples

Content type
application/json
{
  • "flowId": "6613c5c0-642f-4ae7-98ee-a8ccdaa486bb",
  • "processStatus": "active",
  • "scaStatus": "Accepted",
  • "messageId": "20200415-0741-4280-BECA-3A8B2BD86091",
  • "transactions": [
    ]
}

DEPRECATED: Use /api/payments/availability in stead. Used to be: List available due dates for a payment Deprecated

Authorizations:
Authorization
path Parameters
initiatingCountry
required
string <ISO-3166>
Example: NO

Initiating country code, currently the only supported country code is 'NO'

Request Body schema: application/json
amount
required
string

The monetary amount, two decimals, max value 999999999999.99, always positive

toCurrency
required
string

The currency used in the payment

debtorBic
required
string

Debtor's bank BIC

Responses

Request samples

Content type
application/json
{
  • "amount": "string",
  • "toCurrency": "string",
  • "debtorBic": "string"
}

Response samples

Content type
application/json
[
  • "2022-03-24",
  • "2022-03-26"
]

List payment availability and requirements

Authorizations:
Authorization
Request Body schema: application/json
required
object (PaymentAvailabilityRequestFrom)
currency
required
string

The currency of the transaction

bic
required
string

Identifier code for the accounts bank

required
object (PaymentAvailabilityRequestTo)
currency
required
string

The currency of the transaction

bic
required
string

Identifier code for the accounts bank

amount
required
string

The monetary amount, two decimals, max value 999999999999.99, always positive

Responses

Request samples

Content type
application/json
{
  • "from": {
    },
  • "to": {
    }
}

Response samples

Content type
application/json
{
  • "resultCode": "NOT_SUPPORTED",
  • "messages": [
    ],
  • "paymentRequirementInformation": {
    }
}

Cancel Payments

Creates a payment cancellation that is authorized by an existing consent

Authorizations:
Authorization
query Parameters
consentReference
required
string <UUID>
Example: consentReference=b0fc2430-3d87-470d-83f5-a4e94d540f6f

Unique Reference ID given to the Generic Consent request after SCA is completed along with the sca_status, provided in TPP callback URL

header Parameters
Idempotency-Key
required
string <UUID>
Example: 49ae0cfe-6b72-4310-81f5-ad4eef897fe3

Unique identifier for idempotency

PSU-IP-Address
string <ipv4>
Example: 192.158.1.38

AAA IP Address of the end-user initiating the payment. DO NOT use any other IP address than what you can collect from the current user session that uses your system (don't use something stored in your DB). This information is used by the banks to manage traffic and handle security. Mandatory in all calls in Sweden.

PSU-User-Agent
string
Example: Mozilla/5.0 (Windows NT 10.0; …) Gecko/20100101 Firefox/63.0

The forwarded Agent header field of the HTTP request between PSU and TPP, if available

PSU-Geo-Location
string
Example: GEO:52.506931;13.144558

The forwarded value of the Geo Location of the corresponding HTTP request between the PSU and TPP, if available

Request Body schema: application/json
required

Payment Cancellation Request

paymentId
required
string

PSD2 Payment ID, available from the payment status endpoint

callbackUrl
required
string

will be used by the bank to generate a URL where the end user has to provide Strong Customer Authentication. This callbackUrl will include the provided instructionId, allowing the user to track which payment is being cancelled

instructionId
required
string

TPP reference for this payment cancellation, used for callback

Responses

Request samples

Content type
application/json
{
  • "paymentId": "dba8a99a40f24ca594e6c313d1e88018",
  • "callbackUrl": "string",
  • "instructionId": "62f930b774464383ab47576c54fef125"
}

Response samples

Content type
application/json
{
  • "statusReason": {
    },
  • "scaUrl": "string"
}

Payroll

Payroll

Initiate a payroll payment

Authorizations:
Authorization
header Parameters
PSU-IP-Address
required
string <ipv4>
Example: 192.158.1.38

AAA IP Address of the end-user initiating the payment. DO NOT use any other IP address than what you can collect from the current user session that uses your system (don't use something stored in your DB). This information is used by the banks to manage traffic and handle security. Mandatory in all calls in Sweden.

PSU-Geo-Location
string

Geo Location of the one initiating the payment

PSU-User-Agent
string

User agent of the one initiating the payment

Request Body schema: application/json
base64Pain001
required
string

A base64 encoded pain001 xml file

legalId
required
string

The organization identifier of the one initiating the payroll payment

consentReference
required
string

The ID of the payment consent

callbackUrl
required
string

The url the customer is redirected to after confirming payment with SCA

Responses

Request samples

Content type
application/json
{
  • "base64Pain001": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiP...mZJbml0bj4NCjwvRG9jdW1lbnQ+DQo=",
  • "legalId": "NO754987902",
  • "consentReference": "hf7f7ds-f454g",
  • "callbackUrl": "http://callback"
}

Response samples

Content type
application/json
{}

Get payroll payment status

Authorizations:
Authorization
path Parameters
payrollId
required
string <uuid>

Payroll Payment ID

Responses

Response samples

Content type
application/json
{
  • "statusName": "SETTLEMENT_IN_PROGRESS",
  • "statusReason": "Initiated Payment has been accepted for execution",
  • "timestamp": "021-11-30T10:54:34.489808485+01:00"
}

Cancel payroll payment

Creates a payroll payment cancellation that is authorized by an existing consent

Authorizations:
Authorization
header Parameters
Idempotency-Key
required
string <uuid>
Example: 49ae0cfe-6b72-4310-81f5-ad4eef897fe3

Unique identifier for idempotency

PSU-IP-Address
string <ipv4>
Example: 192.158.1.38

AAA IP Address of the end-user initiating the payment. DO NOT use any other IP address than what you can collect from the current user session that uses your system (don't use something stored in your DB). This information is used by the banks to manage traffic and handle security. Mandatory in all calls in Sweden.

PSU-User-Agent
string
Example: Mozilla/5.0 (Windows NT 10.0; …) Gecko/20100101 Firefox/63.0

The forwarded Agent header field of the HTTP request between PSU and TPP, if available

PSU-Geo-Location
string
Example: GEO:52.506931;13.144558

The forwarded value of the Geo Location of the corresponding HTTP request between the PSU and TPP, if available

Request Body schema: application/json
required

Payroll Cancellation Request

payrollId
required
string

The payroll ID used to uniquely identify the payroll payment

consentReference
required
string

The ID of the payroll consent

callbackUrl
required
string

will be used by the bank to generate a URL where the end user has to provide Strong Customer Authentication. This callbackUrl will include the provided payrollId, allowing the user to track which payroll is being cancelled

instructionId
required
string

TPP reference for this payment cancellation, used for callback

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "statusReason": {
    },
  • "scaUrl": "string"
}

Banks

Retrieve available details for supported banks

Supported banks

List of supported banks, with known constraints. Due to variations in the PSD2 APIs of the different banks, initiating a payment with certain banks may be subject to some limitations

Authorizations:
Authorization
path Parameters
countryCode
required
string <ISO-3166>
Example: NO

Country code, ISO-3166 only supported country code is 'NO'

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Companies

Retrieve information about onboarded companies and supported types

Onboarded companies

Get list of companies onboarded

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Supported company types

Get list of supported company types per country

path Parameters
countryCode
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Activate subscription

Activate the subscription for the given company

path Parameters
countryCode
required
string
organizationNumber
required
string

Responses

Response samples

Content type
application/json
{
  • "type": "urn:quote-failed",
  • "title": "Payment rejected",
  • "detail": null,
  • "instance": "/api/payments/56563af2-a199-44ec-92a1-d77eed2d8562/status"
}

Cancel subscription

Cancel the subscription for the given company

path Parameters
countryCode
required
string
organizationNumber
required
string

Responses

Response samples

Content type
application/json
{
  • "type": "urn:quote-failed",
  • "title": "Payment rejected",
  • "detail": null,
  • "instance": "/api/payments/56563af2-a199-44ec-92a1-d77eed2d8562/status"
}

FX Payments

FX can either be used with or without bank integration. For bank integration, please see Flow for Currency CrossBorder transaction with bank integration

FX payment without domestic bank integration flow

The partner is responsible to handle the domestic bank integration, or present the required payment instructions for domestic transaction to the user.

Validation

International payment validation request. Currently only available for selected customers. Please contact us if you're interested in testing this.

Authorizations:
Authorization
header Parameters
Authorization
string <Bearer JWT>
Example: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkE1NEZCQjFGRjgzRTZFRUFEQUI1MTg4QTJBMkVGRDhGNTUzMEUzNDkiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJwVS03SF9nLWJ1cmF0UmlLS2k3OWoxVXc0MGsifQ.eyJuYmYiOjE1NjI4MzE1OTIsImV4cCI6MTU2MjgzNTE5MiwiaXNzIjoiaHR0cHM6Ly9vaWRjLnp0bC5zdGFjY2Zsb3cubmV0IiwiYXVkIjpbImh0dHBzOi8vb2lkYy56dGwuc3RhY2NmbG93Lm5ldC9yZXNvdXJjZXMiLCJ6dGwtYXBpIiwicG9ydGFsLWFwaSJdLCJjbGllbnRfaWQiOiJkZXZjbGllbnQiLCJzY29wZSI6WyJwYXltZW50cyIsInBvcnRhbC1hcGkiXX0.dJuDJNTsSBhQ_xmN3ruqbBZvJdyn2nUkUW3NEwbgXw_l-UA3_XRmtp16rWWdhMLbh-D_HywwG2a0h-MK2tX17C-ggsfp_pDxj8iy8aLleI3dY1qt0VkQY8rOw5_YtWa40HWwIBK9Ll8MqovwBK4lg9Pkq_KLGdkoz87n63QezS5u0JeWYJJnHFuY5ojX_M5szAdSYoVYOyvL0tr30ynxb3joglKrVWlkeawRZztRV4chFN00tlv_Tn54vDYOyDPtBWK6JpMVqhHla8a5JnslJu5dUP82qtgms_lFYOiR1oD2jaa-t0QTE6MVwspG3kwQBSSSZawe-9G4yEBg-nFSGg

Bearer Authorization token - A JWT token used to authenticate the request. Please refer to the Authorization section of our docs.

Request Body schema: application/json
required
object

Metadata for quote request

organizationCountryCode
required
string <ISO 3166-1 alpha-2>

Country

organizationNumber
required
string

The organization number of the company initiating the payment

endToEndId
required
string

An ID that can be used to identify the payment

required
object

Information about the debtor

bban
required
string

Basic Bank Account Number

bic
required
string

Bank Identification Code

required
object

Debtor contact information

name
required
string

The name of the organization making the payment

required
object

The address of the organization making the payment

currency
required
string

The base currency for the payment.

country
required
string <ISO 3166-1 alpha-2>

The country that the payment is being initiated from

required
object

Information about the creditor

required
object

Account information for creditor

iban
required
string

International Bank Account Number

bban
required
string

Basic Bank Account Number

bic
string

Bank Identification Code

clearingCode
string

Code required for payments to certain countries

required
object

Creditor contact information

name
required
string

The name of the organization making the payment

required
object

The address of the organization making the payment

required
object

The amount and currency for the quote

amount
required
string

The amount to get a quote for

currency
required
string

The currency the amount is specified in

dueDate
required
string <date, ISO-8601>

The due date for the payment. NOTE: Currently only the today (i.e. current date) is allowed. Future dates will be enabled in the future

required
object

Remittance information

unstructured
required
string

The address of the organization making the payment

Array of objects
Array
type
required
string
Enum: "TaxCode" "Reason" "Purpose"

Type of additional information. Must be compliant with receiving country rules

  • Reason Text to describe the reason for payment
  • Purpose A valid PurposeCode of the payment
  • TaxCode Receiver Tax code
value
required
string

Value of the property

purposeCode
string
Deprecated

A code stating the purpose of the payment. (Required by some countries). Deprecated - use Information.RemittanceInformation.AdditionalInformation (type - Purpose) instead

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "from": {
    },
  • "to": {
    },
  • "amount": {
    },
  • "dueDate": "2023-01-15",
  • "remittanceInformation": {
    },
  • "purposeCode": "S1008"
}

Response samples

Content type
application/json
[
  • {
    }
]

Payment Initiation

International payment quote request. Currently only available for selected customers. Please contact us if you're interested in testing this.

Authorizations:
Authorization
header Parameters
Authorization
string <Bearer JWT>
Example: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkE1NEZCQjFGRjgzRTZFRUFEQUI1MTg4QTJBMkVGRDhGNTUzMEUzNDkiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJwVS03SF9nLWJ1cmF0UmlLS2k3OWoxVXc0MGsifQ.eyJuYmYiOjE1NjI4MzE1OTIsImV4cCI6MTU2MjgzNTE5MiwiaXNzIjoiaHR0cHM6Ly9vaWRjLnp0bC5zdGFjY2Zsb3cubmV0IiwiYXVkIjpbImh0dHBzOi8vb2lkYy56dGwuc3RhY2NmbG93Lm5ldC9yZXNvdXJjZXMiLCJ6dGwtYXBpIiwicG9ydGFsLWFwaSJdLCJjbGllbnRfaWQiOiJkZXZjbGllbnQiLCJzY29wZSI6WyJwYXltZW50cyIsInBvcnRhbC1hcGkiXX0.dJuDJNTsSBhQ_xmN3ruqbBZvJdyn2nUkUW3NEwbgXw_l-UA3_XRmtp16rWWdhMLbh-D_HywwG2a0h-MK2tX17C-ggsfp_pDxj8iy8aLleI3dY1qt0VkQY8rOw5_YtWa40HWwIBK9Ll8MqovwBK4lg9Pkq_KLGdkoz87n63QezS5u0JeWYJJnHFuY5ojX_M5szAdSYoVYOyvL0tr30ynxb3joglKrVWlkeawRZztRV4chFN00tlv_Tn54vDYOyDPtBWK6JpMVqhHla8a5JnslJu5dUP82qtgms_lFYOiR1oD2jaa-t0QTE6MVwspG3kwQBSSSZawe-9G4yEBg-nFSGg

Bearer Authorization token - A JWT token used to authenticate the request. Please refer to the Authorization section of our docs.

Request Body schema: application/json
required
object

Metadata for quote request

organizationCountryCode
required
string <ISO 3166-1 alpha-2>

Country

organizationNumber
required
string

The organization number of the company initiating the payment

endToEndId
required
string

An ID that can be used to identify the payment

required
object

Information about the debtor

bban
required
string

Basic Bank Account Number

bic
required
string

Bank Identification Code

required
object

Debtor contact information

name
required
string

The name of the organization making the payment

required
object

The address of the organization making the payment

currency
required
string

The base currency for the payment.

country
required
string <ISO 3166-1 alpha-2>

The country that the payment is being initiated from

required
object

Information about the creditor

required
object

Account information for creditor

iban
required
string

International Bank Account Number

bban
required
string

Basic Bank Account Number

bic
string

Bank Identification Code

clearingCode
string

Code required for payments to certain countries

required
object

Creditor contact information

name
required
string

The name of the organization making the payment

required
object

The address of the organization making the payment

required
object

The amount and currency for the quote

amount
required
string

The amount to get a quote for

currency
required
string

The currency the amount is specified in

dueDate
required
string <date, ISO-8601>

The due date for the payment. NOTE: Currently only the today (i.e. current date) is allowed. Future dates will be enabled in the future

required
object

Remittance information

unstructured
required
string

The address of the organization making the payment

Array of objects
Array
type
required
string
Enum: "TaxCode" "Reason" "Purpose"

Type of additional information. Must be compliant with receiving country rules

  • Reason Text to describe the reason for payment
  • Purpose A valid PurposeCode of the payment
  • TaxCode Receiver Tax code
value
required
string

Value of the property

purposeCode
string
Deprecated

A code stating the purpose of the payment. (Required by some countries). Deprecated - use Information.RemittanceInformation.AdditionalInformation (type - Purpose) instead

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "from": {
    },
  • "to": {
    },
  • "amount": {
    },
  • "dueDate": "2023-01-15",
  • "remittanceInformation": {
    },
  • "purposeCode": "S1008"
}

Response samples

Content type
application/json
{
  • "quoteId": "d6f06bfe-4830-4358-b483-c24c66cfb431",
  • "endToEndId": "7c628b2e-9094-4bf8-af23-1d517c6fc4f5",
  • "requestedAmount": {
    },
  • "costAmount": {
    },
  • "exchangeRate": 1.0346,
  • "quoteExpiryTime": "2023-01-15T09:32:00+01:00",
  • "referenceCode": "ZTL-d6f06bfe",
  • "intermediaryAccount": {
    }
}

Payment Confirmation

International payment confirmation. Currently only available for selected customers. Please contact us if you're interested in testing this.

Authorizations:
Authorization
path Parameters
quoteId
required
string

quote id as for payment

header Parameters
Authorization
string <Bearer JWT>
Example: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkE1NEZCQjFGRjgzRTZFRUFEQUI1MTg4QTJBMkVGRDhGNTUzMEUzNDkiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJwVS03SF9nLWJ1cmF0UmlLS2k3OWoxVXc0MGsifQ.eyJuYmYiOjE1NjI4MzE1OTIsImV4cCI6MTU2MjgzNTE5MiwiaXNzIjoiaHR0cHM6Ly9vaWRjLnp0bC5zdGFjY2Zsb3cubmV0IiwiYXVkIjpbImh0dHBzOi8vb2lkYy56dGwuc3RhY2NmbG93Lm5ldC9yZXNvdXJjZXMiLCJ6dGwtYXBpIiwicG9ydGFsLWFwaSJdLCJjbGllbnRfaWQiOiJkZXZjbGllbnQiLCJzY29wZSI6WyJwYXltZW50cyIsInBvcnRhbC1hcGkiXX0.dJuDJNTsSBhQ_xmN3ruqbBZvJdyn2nUkUW3NEwbgXw_l-UA3_XRmtp16rWWdhMLbh-D_HywwG2a0h-MK2tX17C-ggsfp_pDxj8iy8aLleI3dY1qt0VkQY8rOw5_YtWa40HWwIBK9Ll8MqovwBK4lg9Pkq_KLGdkoz87n63QezS5u0JeWYJJnHFuY5ojX_M5szAdSYoVYOyvL0tr30ynxb3joglKrVWlkeawRZztRV4chFN00tlv_Tn54vDYOyDPtBWK6JpMVqhHla8a5JnslJu5dUP82qtgms_lFYOiR1oD2jaa-t0QTE6MVwspG3kwQBSSSZawe-9G4yEBg-nFSGg

Bearer Authorization token - A JWT token used to authenticate the request. Please refer to the Authorization section of our docs.

Responses

Response samples

Content type
application/json
{}

Funding Payment Confirmation

Cross-border payment funding confirmation. Currently only available for selected customers. Please contact us if you're interested in testing this.

Authorizations:
Authorization
path Parameters
paymentId
required
string

paymentId for the payment to be confirmedPaid

header Parameters
Authorization
string <Bearer JWT>
Example: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkE1NEZCQjFGRjgzRTZFRUFEQUI1MTg4QTJBMkVGRDhGNTUzMEUzNDkiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJwVS03SF9nLWJ1cmF0UmlLS2k3OWoxVXc0MGsifQ.eyJuYmYiOjE1NjI4MzE1OTIsImV4cCI6MTU2MjgzNTE5MiwiaXNzIjoiaHR0cHM6Ly9vaWRjLnp0bC5zdGFjY2Zsb3cubmV0IiwiYXVkIjpbImh0dHBzOi8vb2lkYy56dGwuc3RhY2NmbG93Lm5ldC9yZXNvdXJjZXMiLCJ6dGwtYXBpIiwicG9ydGFsLWFwaSJdLCJjbGllbnRfaWQiOiJkZXZjbGllbnQiLCJzY29wZSI6WyJwYXltZW50cyIsInBvcnRhbC1hcGkiXX0.dJuDJNTsSBhQ_xmN3ruqbBZvJdyn2nUkUW3NEwbgXw_l-UA3_XRmtp16rWWdhMLbh-D_HywwG2a0h-MK2tX17C-ggsfp_pDxj8iy8aLleI3dY1qt0VkQY8rOw5_YtWa40HWwIBK9Ll8MqovwBK4lg9Pkq_KLGdkoz87n63QezS5u0JeWYJJnHFuY5ojX_M5szAdSYoVYOyvL0tr30ynxb3joglKrVWlkeawRZztRV4chFN00tlv_Tn54vDYOyDPtBWK6JpMVqhHla8a5JnslJu5dUP82qtgms_lFYOiR1oD2jaa-t0QTE6MVwspG3kwQBSSSZawe-9G4yEBg-nFSGg

Bearer Authorization token - A JWT token used to authenticate the request. Please refer to the Authorization section of our docs.

Responses

Response samples

Content type
application/json
{}

Payment Status

International payment status inquiry. Currently only available for selected customers. Please contact us if you're interested in testing this.

Authorizations:
Authorization
path Parameters
paymentId
required
string

paymentId for the payment

header Parameters
Authorization
string <Bearer JWT>
Example: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkE1NEZCQjFGRjgzRTZFRUFEQUI1MTg4QTJBMkVGRDhGNTUzMEUzNDkiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJwVS03SF9nLWJ1cmF0UmlLS2k3OWoxVXc0MGsifQ.eyJuYmYiOjE1NjI4MzE1OTIsImV4cCI6MTU2MjgzNTE5MiwiaXNzIjoiaHR0cHM6Ly9vaWRjLnp0bC5zdGFjY2Zsb3cubmV0IiwiYXVkIjpbImh0dHBzOi8vb2lkYy56dGwuc3RhY2NmbG93Lm5ldC9yZXNvdXJjZXMiLCJ6dGwtYXBpIiwicG9ydGFsLWFwaSJdLCJjbGllbnRfaWQiOiJkZXZjbGllbnQiLCJzY29wZSI6WyJwYXltZW50cyIsInBvcnRhbC1hcGkiXX0.dJuDJNTsSBhQ_xmN3ruqbBZvJdyn2nUkUW3NEwbgXw_l-UA3_XRmtp16rWWdhMLbh-D_HywwG2a0h-MK2tX17C-ggsfp_pDxj8iy8aLleI3dY1qt0VkQY8rOw5_YtWa40HWwIBK9Ll8MqovwBK4lg9Pkq_KLGdkoz87n63QezS5u0JeWYJJnHFuY5ojX_M5szAdSYoVYOyvL0tr30ynxb3joglKrVWlkeawRZztRV4chFN00tlv_Tn54vDYOyDPtBWK6JpMVqhHla8a5JnslJu5dUP82qtgms_lFYOiR1oD2jaa-t0QTE6MVwspG3kwQBSSSZawe-9G4yEBg-nFSGg

Bearer Authorization token - A JWT token used to authenticate the request. Please refer to the Authorization section of our docs.

Responses

Response samples

Content type
application/json
{
  • "status": "PaymentFailed",
  • "message": "Technical error."
}

Payment Cancellation

International payment funding payment confirmation. Currently only available for selected customers. Please contact us if you're interested in testing this.

Authorizations:
Authorization
path Parameters
paymentId
required
string

paymentId for the payment to cancel

header Parameters
Authorization
string <Bearer JWT>
Example: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkE1NEZCQjFGRjgzRTZFRUFEQUI1MTg4QTJBMkVGRDhGNTUzMEUzNDkiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJwVS03SF9nLWJ1cmF0UmlLS2k3OWoxVXc0MGsifQ.eyJuYmYiOjE1NjI4MzE1OTIsImV4cCI6MTU2MjgzNTE5MiwiaXNzIjoiaHR0cHM6Ly9vaWRjLnp0bC5zdGFjY2Zsb3cubmV0IiwiYXVkIjpbImh0dHBzOi8vb2lkYy56dGwuc3RhY2NmbG93Lm5ldC9yZXNvdXJjZXMiLCJ6dGwtYXBpIiwicG9ydGFsLWFwaSJdLCJjbGllbnRfaWQiOiJkZXZjbGllbnQiLCJzY29wZSI6WyJwYXltZW50cyIsInBvcnRhbC1hcGkiXX0.dJuDJNTsSBhQ_xmN3ruqbBZvJdyn2nUkUW3NEwbgXw_l-UA3_XRmtp16rWWdhMLbh-D_HywwG2a0h-MK2tX17C-ggsfp_pDxj8iy8aLleI3dY1qt0VkQY8rOw5_YtWa40HWwIBK9Ll8MqovwBK4lg9Pkq_KLGdkoz87n63QezS5u0JeWYJJnHFuY5ojX_M5szAdSYoVYOyvL0tr30ynxb3joglKrVWlkeawRZztRV4chFN00tlv_Tn54vDYOyDPtBWK6JpMVqhHla8a5JnslJu5dUP82qtgms_lFYOiR1oD2jaa-t0QTE6MVwspG3kwQBSSSZawe-9G4yEBg-nFSGg

Bearer Authorization token - A JWT token used to authenticate the request. Please refer to the Authorization section of our docs.

Responses

Response samples

Content type
application/json
{
  • "message": "Payment not found.",
  • "correlationId": "7757cdcb-128f-41ba-b3a6-58722e56b0f8"
}

Currencies

FX can either be used with or without bank integration. For bank integration, please see Flow for Currency CrossBorder transaction with bank integration

FX payment without domestic bank integration flow

The partner is responsible to handle the domestic bank integration, or present the required payment instructions for domestic transaction to the user.

Supported currencies

Get details of supported currencies international payments

Authorizations:
Authorization

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Country

Helper methods for cross-border payment support

All countries

List of all countries ZTL supports (receiver)

Authorizations:
Authorization

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Cross-border payment requirements for receiving country

Country payment requirements

Authorizations:
Authorization
path Parameters
country
required
string

2-letters country code

Responses

Response samples

Content type
application/json
{
  • "countryCode": "SE",
  • "countryName": "Sweden",
  • "localCurrency": "NOK",
  • "acceptedCurrencies": [
    ],
  • "supportedBankAccountFormats": [
    ],
  • "paymentRequirements": [
    ]
}