ZTL API Documentation - Back to main docs
API docs by Redocly

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

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 when you initiate an onboarding.

Responses

Response samples

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

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, currently the only supported country code is 'NO'

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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",
  • "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

PSU-IP-Address - The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. If not available, the TPP can use the IP Address used by the TPP when submitting this request.

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

PSU-IP-Address - The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. If not available, the TPP can use the IP Address used by the TPP when submitting this request.

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

PSU-IP-Address - The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. If not available, the TPP can use the IP Address used by the TPP when submitting this request.

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": [
    ]
}

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

PSU-IP-Address - The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. If not available, the TPP can use the IP Address used by the TPP when submitting this request.

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": [
    ]
}

Companies

Retrieve information about onboarded companies and supported types

Supported company types

Get list of supported company types per country

Authorizations:
Authorization
path Parameters
countryCode
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Payments

Payments

Initiate a payment

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

IP Address of the end-user initiating the payment.

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

IP Address of the end-user initiating the payment.

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
{
  • "scaUrl": "https://example-sca-url.com",
  • "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
Example: 153.110.241.229

The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. If not available, the TPP shall use the IP Address used by the TPP when submitting this request

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"
}

FX Payments

Initiation of ZTL Direct payments. This interface is currently in Alpha and available on request only.

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 <Base64 JWT>
Example: eyJhbGciOiJSUzI1NiIsImtpZCI6IkE1NEZCQjFGRjgzRTZFRUFEQUI1MTg4QTJBMkVGRDhGNTUzMEUzNDkiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJwVS03SF9nLWJ1cmF0UmlLS2k3OWoxVXc0MGsifQ.eyJuYmYiOjE1NjI4MzE1OTIsImV4cCI6MTU2MjgzNTE5MiwiaXNzIjoiaHR0cHM6Ly9vaWRjLnp0bC5zdGFjY2Zsb3cubmV0IiwiYXVkIjpbImh0dHBzOi8vb2lkYy56dGwuc3RhY2NmbG93Lm5ldC9yZXNvdXJjZXMiLCJ6dGwtYXBpIiwicG9ydGFsLWFwaSJdLCJjbGllbnRfaWQiOiJkZXZjbGllbnQiLCJzY29wZSI6WyJwYXltZW50cyIsInBvcnRhbC1hcGkiXX0.dJuDJNTsSBhQ_xmN3ruqbBZvJdyn2nUkUW3NEwbgXw_l-UA3_XRmtp16rWWdhMLbh-D_HywwG2a0h-MK2tX17C-ggsfp_pDxj8iy8aLleI3dY1qt0VkQY8rOw5_YtWa40HWwIBK9Ll8MqovwBK4lg9Pkq_KLGdkoz87n63QezS5u0JeWYJJnHFuY5ojX_M5szAdSYoVYOyvL0tr30ynxb3joglKrVWlkeawRZztRV4chFN00tlv_Tn54vDYOyDPtBWK6JpMVqhHla8a5JnslJu5dUP82qtgms_lFYOiR1oD2jaa-t0QTE6MVwspG3kwQBSSSZawe-9G4yEBg-nFSGg

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

purposeCode
string

A code stating the purpose of the payment. (Required by some countries)

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 <Base64 JWT>
Example: eyJhbGciOiJSUzI1NiIsImtpZCI6IkE1NEZCQjFGRjgzRTZFRUFEQUI1MTg4QTJBMkVGRDhGNTUzMEUzNDkiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJwVS03SF9nLWJ1cmF0UmlLS2k3OWoxVXc0MGsifQ.eyJuYmYiOjE1NjI4MzE1OTIsImV4cCI6MTU2MjgzNTE5MiwiaXNzIjoiaHR0cHM6Ly9vaWRjLnp0bC5zdGFjY2Zsb3cubmV0IiwiYXVkIjpbImh0dHBzOi8vb2lkYy56dGwuc3RhY2NmbG93Lm5ldC9yZXNvdXJjZXMiLCJ6dGwtYXBpIiwicG9ydGFsLWFwaSJdLCJjbGllbnRfaWQiOiJkZXZjbGllbnQiLCJzY29wZSI6WyJwYXltZW50cyIsInBvcnRhbC1hcGkiXX0.dJuDJNTsSBhQ_xmN3ruqbBZvJdyn2nUkUW3NEwbgXw_l-UA3_XRmtp16rWWdhMLbh-D_HywwG2a0h-MK2tX17C-ggsfp_pDxj8iy8aLleI3dY1qt0VkQY8rOw5_YtWa40HWwIBK9Ll8MqovwBK4lg9Pkq_KLGdkoz87n63QezS5u0JeWYJJnHFuY5ojX_M5szAdSYoVYOyvL0tr30ynxb3joglKrVWlkeawRZztRV4chFN00tlv_Tn54vDYOyDPtBWK6JpMVqhHla8a5JnslJu5dUP82qtgms_lFYOiR1oD2jaa-t0QTE6MVwspG3kwQBSSSZawe-9G4yEBg-nFSGg

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

purposeCode
string

A code stating the purpose of the payment. (Required by some countries)

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 <Base64 JWT>
Example: eyJhbGciOiJSUzI1NiIsImtpZCI6IkE1NEZCQjFGRjgzRTZFRUFEQUI1MTg4QTJBMkVGRDhGNTUzMEUzNDkiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJwVS03SF9nLWJ1cmF0UmlLS2k3OWoxVXc0MGsifQ.eyJuYmYiOjE1NjI4MzE1OTIsImV4cCI6MTU2MjgzNTE5MiwiaXNzIjoiaHR0cHM6Ly9vaWRjLnp0bC5zdGFjY2Zsb3cubmV0IiwiYXVkIjpbImh0dHBzOi8vb2lkYy56dGwuc3RhY2NmbG93Lm5ldC9yZXNvdXJjZXMiLCJ6dGwtYXBpIiwicG9ydGFsLWFwaSJdLCJjbGllbnRfaWQiOiJkZXZjbGllbnQiLCJzY29wZSI6WyJwYXltZW50cyIsInBvcnRhbC1hcGkiXX0.dJuDJNTsSBhQ_xmN3ruqbBZvJdyn2nUkUW3NEwbgXw_l-UA3_XRmtp16rWWdhMLbh-D_HywwG2a0h-MK2tX17C-ggsfp_pDxj8iy8aLleI3dY1qt0VkQY8rOw5_YtWa40HWwIBK9Ll8MqovwBK4lg9Pkq_KLGdkoz87n63QezS5u0JeWYJJnHFuY5ojX_M5szAdSYoVYOyvL0tr30ynxb3joglKrVWlkeawRZztRV4chFN00tlv_Tn54vDYOyDPtBWK6JpMVqhHla8a5JnslJu5dUP82qtgms_lFYOiR1oD2jaa-t0QTE6MVwspG3kwQBSSSZawe-9G4yEBg-nFSGg

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

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 be confirmedPaid

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

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 <Base64 JWT>
Example: eyJhbGciOiJSUzI1NiIsImtpZCI6IkE1NEZCQjFGRjgzRTZFRUFEQUI1MTg4QTJBMkVGRDhGNTUzMEUzNDkiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJwVS03SF9nLWJ1cmF0UmlLS2k3OWoxVXc0MGsifQ.eyJuYmYiOjE1NjI4MzE1OTIsImV4cCI6MTU2MjgzNTE5MiwiaXNzIjoiaHR0cHM6Ly9vaWRjLnp0bC5zdGFjY2Zsb3cubmV0IiwiYXVkIjpbImh0dHBzOi8vb2lkYy56dGwuc3RhY2NmbG93Lm5ldC9yZXNvdXJjZXMiLCJ6dGwtYXBpIiwicG9ydGFsLWFwaSJdLCJjbGllbnRfaWQiOiJkZXZjbGllbnQiLCJzY29wZSI6WyJwYXltZW50cyIsInBvcnRhbC1hcGkiXX0.dJuDJNTsSBhQ_xmN3ruqbBZvJdyn2nUkUW3NEwbgXw_l-UA3_XRmtp16rWWdhMLbh-D_HywwG2a0h-MK2tX17C-ggsfp_pDxj8iy8aLleI3dY1qt0VkQY8rOw5_YtWa40HWwIBK9Ll8MqovwBK4lg9Pkq_KLGdkoz87n63QezS5u0JeWYJJnHFuY5ojX_M5szAdSYoVYOyvL0tr30ynxb3joglKrVWlkeawRZztRV4chFN00tlv_Tn54vDYOyDPtBWK6JpMVqhHla8a5JnslJu5dUP82qtgms_lFYOiR1oD2jaa-t0QTE6MVwspG3kwQBSSSZawe-9G4yEBg-nFSGg

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 <Base64 JWT>
Example: eyJhbGciOiJSUzI1NiIsImtpZCI6IkE1NEZCQjFGRjgzRTZFRUFEQUI1MTg4QTJBMkVGRDhGNTUzMEUzNDkiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJwVS03SF9nLWJ1cmF0UmlLS2k3OWoxVXc0MGsifQ.eyJuYmYiOjE1NjI4MzE1OTIsImV4cCI6MTU2MjgzNTE5MiwiaXNzIjoiaHR0cHM6Ly9vaWRjLnp0bC5zdGFjY2Zsb3cubmV0IiwiYXVkIjpbImh0dHBzOi8vb2lkYy56dGwuc3RhY2NmbG93Lm5ldC9yZXNvdXJjZXMiLCJ6dGwtYXBpIiwicG9ydGFsLWFwaSJdLCJjbGllbnRfaWQiOiJkZXZjbGllbnQiLCJzY29wZSI6WyJwYXltZW50cyIsInBvcnRhbC1hcGkiXX0.dJuDJNTsSBhQ_xmN3ruqbBZvJdyn2nUkUW3NEwbgXw_l-UA3_XRmtp16rWWdhMLbh-D_HywwG2a0h-MK2tX17C-ggsfp_pDxj8iy8aLleI3dY1qt0VkQY8rOw5_YtWa40HWwIBK9Ll8MqovwBK4lg9Pkq_KLGdkoz87n63QezS5u0JeWYJJnHFuY5ojX_M5szAdSYoVYOyvL0tr30ynxb3joglKrVWlkeawRZztRV4chFN00tlv_Tn54vDYOyDPtBWK6JpMVqhHla8a5JnslJu5dUP82qtgms_lFYOiR1oD2jaa-t0QTE6MVwspG3kwQBSSSZawe-9G4yEBg-nFSGg

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/problem+json
{
  • "message": "Payment not found.",
  • "correlationId": "7757cdcb-128f-41ba-b3a6-58722e56b0f8"
}

Payroll

Payroll

Initiate a payroll payment

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

IP Address of the end-user initiating the payment

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

fundingWithdrawalDate
string <date>

The preferred date for withdrawal of funding payment from customer's account to ZTL's client account

Responses

Request samples

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

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
Example: 153.110.241.229

The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. If not available, the TPP shall use the IP Address used by the TPP when submitting this request

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 instructionId, 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
{
  • "payrollId": "3738a8d3-9f39-49d4-8b4f-6657abb0469f",
  • "consentReference": "hf7f7ds-f454g",
  • "callbackUrl": "http://callback",
  • "instructionId": "62f930b774464383ab47576c54fef125"
}

Response samples

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

Currencies

Supported currencies

Get details of supported currencies international payments

Authorizations:
Authorization

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Payments V2

Our next generation payments API for ERPs. This interface is currently in Alpha and available on request only.

WARNING: This is currently even pre-alpha and changes to the API will be introduced without warning. The flow of events should be fairly stable though.

Highlights:

  • Separate transactions, feedback on validations and errors for each one. This enables the user to complete each transaction and move on to the next one with higher confidence.
  • Choose which transactions to sign. Even if the user has added 5 transactions, she can choose to sign only 4.
  • Multiple authentication methods

Payment Initiation

Validate and initiate payment

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

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

Quote request metadata

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
bban
required
string

Basic Bank Account Number

bic
required
string

Bank Identification Code

required
object (ContactInformation)
name
required
string

The name of the organization making the payment

required
object

Address information for payee

currency
required
string

The currency for the payment.

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

The country that the payment is being initiated from

required
object

Account information for creditor

bban
required
string

Basic Bank Account Number

bic
required
string

Bank Identification Code

clearingCode
string

Code required for payments to certain countries

object (ContactInformation)
name
required
string

The name of the organization making the payment

required
object

Address information for payee

required
object
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 non-empty

One type of remittance information is required

unstructured
string

The unstructured remittance information.

structured
string

The structured remittance information. This is country specific and depends on it being a domestic transfer, and the specific rules for the country.

purposeCode
string

A code stating the purpose of the payment. (Required by some countries)

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 Approval

Initiate approval of transactions

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

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

Request Body schema: application/json
payments
required
Array of uuid non-empty unique
required
ApprovalRedirectRequestDetails (object) or ApprovalDetachedRequestDetails (object)
Any of
method
required
string
Value: "redirect"
confirmationUrl
required
string

A URL that the user will be returned to in the event of a completed approval

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}