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

ZTL OpenAPI (v2.0)

Download OpenAPI specification:Download

Ztl Payment solution api

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

General

  • All responses contain 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"
}

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

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

Country code, ISO-3166

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Consent

API for consents. We try to provide a failure enum when possible, you should expect us to add more values here continuously.

Endpoint for revoking consent is not implemented yet.

Create consent

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.

PSU-IP-Address
required
integer <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.

PSU-User-Agent
required
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. Required in Sweden.

Request Body schema: application/json
userId
required
string

The userId of the account owner providing consent. Different banks use different userId schema, Could be SSN or a userId provided by the bank.

bic
required
string

The bank's international code/address. Also know as Swift code.

callbackUrl
required
string

Sca callback url for Redirect authentication

organizationNumber
required
string

The organization number

preferredScaMethod
string
Enum: "Qr" "Redirect"

The preferred way to perform authorization. There is no guarantee that bank supports the preferred method.

  • Qr Used with bank app to scan image.
  • Redirect Redirect link to redirect authorization flow.
bankBranch
string

Which branch of the bank if multiple. Can be fetched from supported banks endpoint.

Responses

Request samples

Content type
application/json
{
  • "userId": "string",
  • "bic": "ESSESESS",
  • "callbackUrl": "https://www.google.com",
  • "organizationNumber": 1234567890,
  • "preferredScaMethod": "Qr",
  • "bankBranch": "string"
}

Response samples

Content type
application/json
{}

Consent status

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.

consent-id
required
string <uuid>
Example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9

A valid consentId

PSU-IP-Address
integer <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.

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. Required in Sweden.

Responses

Response samples

Content type
application/json
{}

Accounts

API for getting account information. We try to provide a failure enum when possible, you should expect us to add more values here continuously.

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.

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.

consent-id
required
string <uuid>
Example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9

A valid consentId

PSU-IP-Address
integer <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.

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. Required in Sweden.

Responses

Response samples

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

Account Balance

Retrieve the current available and booked balance for the account specified.

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.

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.

consent-id
required
string <uuid>
Example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9

A valid consentId

PSU-IP-Address
integer <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.

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. Required in Sweden.

Responses

Response samples

Content type
application/json
{
  • "id": "11ab5740-f8f5-1234-abcd-b90e4253b7b8",
  • "balance": {
    }
}

Account Entries

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

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
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
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.

consent-id
required
string <uuid>
Example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9

A valid consentId

PSU-IP-Address
integer <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.

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. Required in Sweden.

Responses

Response samples

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

Payments

General changes from v1:

  • Support for banks in Norway, Sweden and Denmark
  • Separate transaction and signing process. Transactions are independent of each other. This makes it easier to validate that each transaction is created correctly, or if the bank for some reason rejected it.
  • Signing/SCA with one or more created transactions. Possible to choose exactly which transactions to sign. Multiple sign requests can be created for a transaction if a correction of input was needed.
  • Possible to create PSD2 funding payment transaction based on FX
  • Possible to choose preferred signing method (Redirect, QR) for banks supporting both methods (Sweden only)

Bank transaction flow chart

Cross-Border Payment with Currency Exchange flow chart

For cross-border payments, an FX payment is created to get a quote and confirm booking. We recommend to use the country requirement API to retrieve payment requirements for the receiving country, which may be used to present required user inputs. Supported country list is optional, as the country is easily obtained based on receiver Swift/BIC. Once the FX payment has been created, partner should create a domestic psd2 transaction by using the fromFx API, and follow the flow from Bank transaction flow chart after the FX transaction has been created.

Payment initiation

Validate and initiate 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.

consent-id
required
string <uuid>
Example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9

A valid consentId

PSU-IP-Address
required
integer <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.

PSU-User-Agent
required
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. Required in Sweden.

Request Body schema: application/json
required
object

Metadata for the payment

endToEndId
required
string

An ID that can be used to identify the payment

required
object

Account information for debtor

required
PaymentAccountBban (object) or PaymentAccountIban (object)
Any of
type
required
string
Value: "bban"
bban
required
string

Account number

required
object (ContactInformation)
name
required
string

The name of the organization making the payment

telephoneNumber
string

Phone number for the organization

object

Address information for payee

currency
required
string

Currency on from account

required
object

Account information for creditor

required
PaymentAccountBban (object) or PaymentAccountIban (object) or PaymentAccountFik (object) or SwedishGiro (object)
Any of
type
required
string
Value: "bban"
bban
required
string

Account number

required
object (ContactInformation)
name
required
string

The name of the organization making the payment

telephoneNumber
string

Phone number for the organization

object

Address information for payee

required
object

Amount and currency to be paid

amount
required
string

Amount to be paid

currency
required
string

The currency the amount is specified in

dueDate
required
string <date, ISO-8601>

The due date for the payment

RemittanceInformationMessage (object) or RemittanceInformationOcr (object) or RemittanceInformationFik (object)

remittance information

Any of
type
required
string
Value: "message"
value
required
string

Message for receiver

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "paymentId": "7c628b2e-9094-4bf8-af23-1d517c6fc4f5",
  • "paymentStatus": {
    }
}

Payment approval

Initiate approval of transactions

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.

consent-id
required
string <uuid>
Example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9

A valid consentId

PSU-IP-Address
required
integer <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.

PSU-User-Agent
required
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. Required in Sweden.

Request Body schema: application/json
payments
required
Array of strings <uuid> non-empty unique [ items <uuid > ]
callbackUrl
required
string

Sca callback url for redirect authentication

preferredScaMethod
string
Enum: "Redirect" "Qr"

Responses

Request samples

Content type
application/json
{
  • "payments": [
    ],
  • "callbackUrl": "https://www.google.com",
  • "preferredScaMethod": "Redirect"
}

Response samples

Content type
application/json
{}

Payment status

Get status of a payment

path Parameters
PaymentId
required
string
Example: 7c628b2e-9094-4bf8-af23-1d517c6fc4f5

Id received when creating 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": "Unsigned",
  • "statusReason": null,
  • "statusReasonText": "string",
  • "timestamp": "2024-03-19T09:34:57.657733682+01:00"
}

Payment approval status

Approval status

path Parameters
id
required
string
Example: 7c628b2e-9094-4bf8-af23-1d517c6fc4f5

Id received when creating an approval for payments

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.

consent-id
required
string <uuid>
Example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9

A valid consentId

PSU-IP-Address
required
integer <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.

PSU-User-Agent
required
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. Required in Sweden.

Responses

Response samples

Content type
application/json
{}

Cancel payment

Initiate cancellation of a 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.

consent-id
required
string <uuid>
Example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9

A valid consentId

PSU-IP-Address
integer <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.

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. Required in Sweden.

Request Body schema: application/json
paymentId
required
string

Id of the payment to cancel

callbackUrl
required
string

Callback url for redirect authentication, if cancellation requires sca

preferredScaMethod
string
Enum: "Redirect" "Qr"

Responses

Request samples

Content type
application/json
{
  • "paymentId": "7c628b2e-9094-4bf8-af23-1d517c6fc4f5",
  • "callbackUrl": "https://www.google.com",
  • "preferredScaMethod": "Redirect"
}

Response samples

Content type
application/json
{
  • "id": null,
  • "sca": null,
  • "cancellationRequestStatus": "ACCEPTED",
  • "currentPaymentStatus": {
    },
  • "reason": null
}

Domestic from FX

Create a funding transaction for FX

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.

consent-id
required
string <uuid>
Example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9

A valid consentId

PSU-IP-Address
required
integer <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.

PSU-User-Agent
required
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. Required in Sweden.

Request Body schema: application/json
fxPaymentId
required
string

Id of the FX payment

Responses

Request samples

Content type
application/json
{
  • "fxPaymentId": "7c628b2e-9094-4bf8-af23-1d517c6fc4f5"
}

Response samples

Content type
application/json
{
  • "paymentId": "7c628b2e-9094-4bf8-af23-1d517c6fc4f5",
  • "paymentStatus": {
    }
}

Initiate bulk payment(s)

Initiates a list of payments. This endpoint is exclusively supported for banks that do not support payment baskets, currently limited to Danske Bank. For other banks, please refer to the Payment Initiation v2 and Payment Approval v2 endpoints.

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.

consent-id
required
string <uuid>
Example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9

A valid consentId

PSU-IP-Address
required
integer <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.

PSU-User-Agent
required
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. Required in Sweden.

Request Body schema: application/json
required
Array of objects (CreatePayment) non-empty
Array (non-empty)
required
object

Metadata for the payment

required
object

Account information for debtor

required
object

Account information for creditor

required
object

Amount and currency to be paid

dueDate
required
string <date, ISO-8601>

The due date for the payment

RemittanceInformationMessage (object) or RemittanceInformationOcr (object) or RemittanceInformationFik (object)

remittance information

callbackUrl
required
string

Sca callback url for redirect authentication

Responses

Request samples

Content type
application/json
{
  • "payments": [
    ],
  • "callbackUrl": "https://www.google.com"
}

Response samples

Content type
application/json
{}

Fetch status for bulk

Fetches the status of a bulk along with the individual payments.

path Parameters
bulkId
required
string
Example: 7c628b2e-9094-4bf8-af23-1d517c6fc4f5

Id received when creating bulk 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.

consent-id
required
string <uuid>
Example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9

A valid consentId

PSU-IP-Address
integer <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.

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. Required in Sweden.

Responses

Response samples

Content type
application/json
{
  • "bulkStatus": "CREATED",
  • "transactions": [
    ]
}

Onboarding

New onboarding.

WARNING: Currently in Alpha, get in touch to investigate.

Things to consider in your implementation:

  • in PRODUCTION each company should be allowed to start an onboarding only once until it reaches a final status, which is either "Approved" or "Rejected"
  • SANDBOX allows to start several onboardings per company for testing purposes and due to the limited test data, see the list below

Testing signing in Sweden

To test the whole onboarding flow including signing the agreement in SANDBOX you need to follow these steps:

  • create a test BankID here: https://www.bankid.com/en/utvecklare/test/skaffa-testbankid using one of the personal numbers provided with the organization numbers in the list below
  • use the same organization number to start an onboarding
  • in the onboarding process, when choosing a signing combination pick the combination with a single person matching the name of the personal number used for creation of test BankID and complete the signing process

Test organization numbers:

  • 5560572850
  • 5565002465
  • 8430025331
  • 5569030264
  • 6805029268 (personal number 196805029268, Efternamn2401, Petra)
  • 5564779444 (personal number 196805029268, Efternamn2401, Petra)
  • 5569994600 (personal number 197904182396, Efternamn2993, Kuno)
  • 9168937861
  • 5590506506 (personal number 196501022773, Pinoz Harem)
  • 5565002465
  • 5164010133
  • 5590672613
  • 8110022392 (personal number 198110022392, Efternamn3672, Ebbe)
  • 9697715770
  • 5564866803 (personal number 196805029268, Efternamn2401, Petra)
  • 5564881422 (personal number 198110022392, Efternamn3672, Ebbe)

Testing signing in Denmark

To test the whole onboarding flow including signing the agreement in SANDBOX you need to follow these steps:

  • create a test MitID here: https://pp.mitid.dk/test-tool/frontend/#/create-identity using one of the names provided with the organization numbers in the list below (rest of the data can be autofilled)
  • use the same organization number to start an onboarding
  • in the onboarding process, when choosing a signing combination pick the combination with a single person matching the name used for creation of test MitID and complete the signing process

Test organization numbers:

  • 23456788 (name: Christian Svanholm-Nielsen)
  • 41773863 (name: Sven Holst)
  • 12345674 (name: Tage Olsen)
  • 38724991 (name: Bettina Christiansen)

Initiate onboarding

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
country
required
string
organizationNumber
required
string

Responses

Request samples

Content type
application/json
{
  • "country": "SE",
  • "organizationNumber": "5569994600"
}

Response samples

Content type
application/json
{}

Get Onboarding status

path Parameters
onboardingId
required
string <uuid>
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": "Approved"
}

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