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
- 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.
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
- 200
- default
{- "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"
}Start an onboarding
Authorizations:
Request Body schema: application/json
| organizationId required | string |
| webhookUrl | string |
| redirectUrl | string |
Responses
Request samples
- Payload
{- "organizationId": "981078365",
}Response samples
- 200
- 201
- default
{- "flowId": "8665acd8-c033-4386-b9ca-ccc6c6a81243",
}Get onboarding status and information
Authorizations:
path Parameters
| flowId required | string Onboarding flowId, returned after initiating an onboarding. |
Responses
Response samples
- 200
- default
{- "orgName": "Ztl",
- "orgNo": "12345678",
- "status": "completed",
- "tasks": [ ],
- "webhookStatuses": {
- "complete": {
- "status": "success",
- "timestamp": "2021-12-16T18:19:55.267Z"
}
}
}Check status of the consent
Authorizations:
query Parameters
| consentAuthorizationId required | string Consent Authorization Id |
Responses
Response samples
- 200
- 400
- 403
{- "reason": "string",
- "status": "string",
- "authorizationType": "SINGLE_AIS,RECURRING_AIS",
- "consentState": {
- "aisExpired": true,
- "pisExpired": true,
- "cafExpired": true
}, - "expirationDate": "2019-08-24T14:15:22Z"
}Create consent
Authorizations:
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/jsonrequired
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
- Payload
{- "callbackUrl": "string",
- "accountOwnerSsn": "string",
- "accountOwnerOrganizationReference": "string",
- "debtorBankBic": "string",
- "instructionId": "string"
}Response samples
- 200
- 400
{- "scaUrl": "string",
- "consentAuthorizationId": "string",
- "status": "string",
- "reason": "string",
- "expirationDate": "2019-08-24T14:15:22Z"
}Revoke Consent
Authorizations:
header Parameters
| Consent-Reference required | string <UUID> Example: b0fc2430-3d87-470d-83f5-a4e94d540f6f Consent Reference to be revoked |
Responses
Response samples
- 400
{- "type": "urn:input-validation-failed",
- "title": "Bad Request",
- "detail": "Missing required header Consent-Reference"
}Account Balance
Retrieve the current available and booked balance for the account or accounts specified in the authorized query.
Authorizations:
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 |
| consentReference required | string <uuid> Example: consentReference=b0fc2430-3d87-470d-83f5-a4e94d540f6f The Consent Reference, as retrieved from the |
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
- 200
- 400
- 500
{- "id": "22cc5740-f8f5-1234-abcd-b90e42531234",
- "name": "Spending account",
- "bic": "DNBANOKK",
- "bban": 12043175449,
- "iban": "NO0812043175449",
- "country": "NO",
- "type": "Debit",
- "currency": "NOK",
- "balance": {
- "booked": {
- "amount": "150.00",
- "currency": "NOK"
}, - "available": {
- "amount": "100.00",
- "currency": "NOK"
}
}
}Account Entries
Retrieve the latest transaction entries on the account or accounts specified in the authorized query.
Authorizations:
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 |
| 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
- 200
- 400
- 500
- 503
{- "account": {
- "id": "11ab5740-f8f5-1234-abcd-b90e4253b7b8",
- "name": "Main savings account",
- "bic": "DNBANOKK",
- "bban": "12043175449",
- "iban": "NO0812043175449",
- "country": "NO",
- "type": "Debit",
- "currency": "NOK",
- "ownerName": "string"
}, - "accountEntries": [
- {
- "transactionId": "d1f669f2-1234-abcd-aabb-ff0cc229b485",
- "postedAmount": {
- "amount": "99.50",
- "currency": "NOK"
}, - "type": "Debit",
- "status": "Pending",
- "bookingDateTime": "2022-01-02",
- "valueDateTime": "2022-01-01",
- "purposeText": "Overføring Innland",
- "remittanceInformation": {
- "reference": 75025049,
- "unstructured": "Transfer of funds"
}, - "creditor": {
- "name": "string",
- "bban": 12043175449,
- "iban": "NO0812043175449"
}, - "debtor": {
- "name": "string",
- "bban": 12043175449,
- "iban": "NO0812043175449"
}, - "endToEndId": "string"
}
]
}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:
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 |
| 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
- 200
- 400
- 500
- 503
{- "transactionId": "d1f669f2-1234-abcd-aabb-ff0cc229b485",
- "postedAmount": {
- "amount": "99.50",
- "currency": "NOK"
}, - "type": "Debit",
- "status": "Pending",
- "bookingDateTime": "2022-01-02",
- "valueDateTime": "2022-01-01",
- "purposeText": "Overføring Innland",
- "remittanceInformation": {
- "reference": 75025049,
- "unstructured": "Transfer of funds"
}, - "creditor": {
- "name": "string",
- "bban": 12043175449,
- "iban": "NO0812043175449"
}, - "debtor": {
- "name": "string",
- "bban": 12043175449,
- "iban": "NO0812043175449"
}, - "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:
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
- 200
- 400
- 403
- 500
{- "accounts": [
- {
- "id": "11ab5740-f8f5-1234-abcd-b90e4253b7b8",
- "name": "Main savings account",
- "bic": "DNBANOKK",
- "bban": "12043175449",
- "iban": "NO0812043175449",
- "country": "NO",
- "type": "Debit",
- "currency": "NOK",
- "ownerName": "string"
}
]
}Initiate a payment
Authorizations:
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
- Payload
{- "idempotencyKey": "123123-123-12-2222",
- "countryCode": "NO",
- "organizationId": "123456789",
- "consentReference": "123123-123123-123123-2",
- "base64Pain001": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiP...mZJbml0bj4NCjwvRG9jdW1lbnQ+DQo="
}Response samples
- 201
- 400
{- "flowId": "8665acd8-c033-4386-b9ca-ccc6c6a81243",
}Validate a payment
Authorizations:
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
- Payload
{- "idempotencyKey": "123123-123-12-2222",
- "countryCode": "NO",
- "organizationId": "123456789",
- "consentReference": "123123-123123-123123-2",
- "base64Pain001": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiP...mZJbml0bj4NCjwvRG9jdW1lbnQ+DQo="
}Response samples
- 400
{- "type": "urn:pain-invalid",
- "title": "Invalid Pain",
- "detail": "There are 2 errors",
- "detail2": "",
- "errors": [
- {
- "type": "transaction",
- "endToEndId": "966700472476787235510074468580",
- "errors": [
- {
- "code": "urn:max-length-exceeded",
- "path": "CstmrCdtTrfInitn.PmtInf[0].CdtTrfTxInf[0].rmtInf",
- "message": "Payment reference is too long for the receiver's bank",
- "developerText": "Unstructured remittance info is too long for debtor agent DNBANOKK. The current length is 46, while the maximum length is 35."
}
]
}, - {
- "type": "general",
- "errors": [
- {
- "code": "urn:country-missing",
- "path": "cstmrCdtTrfInitn.PmtInf[0].Dbtr.PstlAdr.Ctry",
- "message": "Country is required for debtor postal address",
- "developerText": "Country tag <Ctry> is required for <Dbtr><PstlAdr>"
}
]
}
], - "traceId": "03f55df4-d7d7-416a-add6-0f427eec7f92"
}Get payment information
Authorizations:
path Parameters
| flowId required | string <uuid> Payment ID |
Responses
Response samples
- 200
{- "flowId": "6613c5c0-642f-4ae7-98ee-a8ccdaa486bb",
- "processStatus": "active",
- "scaStatus": "Accepted",
- "messageId": "20200415-0741-4280-BECA-3A8B2BD86091",
- "transactions": [
- {
- "endToEndID": "296edf186a374b0a89edfa8e9fd054c5",
- "status": "AcceptedSettlementInProgress",
- "statusReason": "Payment accepted at Aspsp and needs to be signed by PSU. Please initiate payment signing process",
- "purposeCode": "OTHR",
- "transactionAmount": {
- "amount": "1235",
- "currency": "NOK"
}, - "commission": {
- "amount": "0",
- "currency": "NOK"
}, - "fromCurrency": "NOK",
- "toCurrency": "NOK",
- "exchangeRate": 1,
- "paymentId": "0fsdfasdfsa3e4d46218b80179d5c19f796",
- "dueDate": "2022-02-08"
}, - {
- "endToEndID": "wd459dp10b7plasjdl202aas5",
- "status": "AcceptedSettlementInProgress",
- "statusReason": "Payment accepted at Aspsp and needs to be signed by PSU. Please initiate payment signing process",
- "purposeCode": "OTHR",
- "transactionAmount": {
- "amount": "9608.8",
- "currency": "SEK"
}, - "commission": {
- "amount": "1.5",
- "currency": "NOK"
}, - "fromCurrency": "NOK",
- "toCurrency": "SEK",
- "exchangeRate": 0.9688,
- "displayExchangeRate": 96.88,
- "exchangeRateExpiration": "2022-08-05T14:48:14.133+02:00",
- "paymentId": "5fdff9c50523460585c7fc93038791ae",
- "dueDate": "2022-02-08"
}
]
}DEPRECATED: Use /api/payments/availability in stead. Used to be: List available due dates for a payment Deprecated
Authorizations:
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
- Payload
{- "amount": "string",
- "toCurrency": "string",
- "debtorBic": "string"
}Response samples
- 200
- 400
[- "2022-03-24",
- "2022-03-26"
]List payment availability and requirements
Authorizations:
Request Body schema: application/json
required | object (PaymentAvailabilityRequestFrom) | ||||||
| |||||||
required | object (PaymentAvailabilityRequestTo) | ||||||
| |||||||
Responses
Request samples
- Payload
{- "from": {
- "currency": "NOK",
- "bic": "DNBANOKK"
}, - "to": {
- "currency": "NOK",
- "bic": "DNBANOKK",
- "amount": "99.50"
}
}Response samples
- 200
{- "resultCode": "NOT_SUPPORTED",
- "messages": [
- {
- "type": "urn:not-supported",
- "message": "We don't support THB"
}
], - "paymentRequirementInformation": {
- "paymentRequirements": [
- {
- "type": "BIC",
- "validationPattern": "[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}",
- "description": "Invalid BIC"
}
], - "validDates": [
- "2022-11-15"
]
}
}Cancel Payments
Creates a payment cancellation that is authorized by an existing consent
Authorizations:
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/jsonrequired
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
- Payload
{- "paymentId": "dba8a99a40f24ca594e6c313d1e88018",
- "callbackUrl": "string",
- "instructionId": "62f930b774464383ab47576c54fef125"
}Response samples
- 201
- 400
- 500
{- "statusReason": {
- "reason": "Payment accepted at Aspsp and needs to be signed by PSU. Please initiate payment signing process",
- "status": "AuthorizationRequired",
- "origin": "NAAS"
}, - "scaUrl": "string"
}Initiate a payroll payment
Authorizations:
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
- Payload
{- "base64Pain001": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiP...mZJbml0bj4NCjwvRG9jdW1lbnQ+DQo=",
- "legalId": "NO754987902",
- "consentReference": "hf7f7ds-f454g",
}Response samples
- 201
- 400
- 422
{- "payrollId": "8665acd8-c033-4386-b9ca-ccc6c6a81243",
}Get payroll payment status
Authorizations:
path Parameters
| payrollId required | string <uuid> Payroll Payment ID |
Responses
Response samples
- 200
{- "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:
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/jsonrequired
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
- Payload
{- "payrollId": "3738a8d3-9f39-49d4-8b4f-6657abb0469f",
- "consentReference": "hf7f7ds-f454g",
- "instructionId": "62f930b774464383ab47576c54fef125"
}Response samples
- 200
- 400
- 404
- 423
- 500
{- "statusReason": {
- "reason": "Payment accepted at Aspsp and needs to be signed by PSU. Please initiate payment signing process",
- "status": "AuthorizationRequired",
- "origin": "NAAS"
}, - "scaUrl": "string"
}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:
path Parameters
| countryCode required | string <ISO-3166> Example: NO Country code, ISO-3166 only supported country code is 'NO' |
Responses
Response samples
- 200
- 400
[- {
- "bic": "DNBANOKK",
- "constraints": {
- "maxBasketSize": 20,
- "maxInformationFieldLength": 35,
- "maxUnstructuredRemittanceInfoLength": 108,
- "aisMaxDateRangeMonths": 12,
- "cancelSCARequired": true,
- "validInformationFieldCharactersPattern": "[A-ZÆØÅa-zæøå0-9\\\\D]",
- "maxBulkSize": 20
}, - "countryCode": "NO",
- "name": "DNB BANK ASA",
- "supportedProducts": [
- "PAYMENT_DOMESTIC"
]
}
]Activate subscription
Activate the subscription for the given company
path Parameters
| countryCode required | string |
| organizationNumber required | string |
Responses
Response samples
- 400
{- "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
- 400
{- "type": "urn:quote-failed",
- "title": "Payment rejected",
- "detail": null,
- "instance": "/api/payments/56563af2-a199-44ec-92a1-d77eed2d8562/status"
}FX can either be used with or without bank integration. For bank integration, please see Flow for Currency CrossBorder transaction with bank integration
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:
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 | ||||||||||||||||||||
| |||||||||||||||||||||
required | object Information about the debtor | ||||||||||||||||||||
| |||||||||||||||||||||
required | object Information about the creditor | ||||||||||||||||||||
| |||||||||||||||||||||
required | object The amount and currency for the quote | ||||||||||||||||||||
| |||||||||||||||||||||
| 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 | ||||||||||||||||||||
| |||||||||||||||||||||
| 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
- Payload
{- "metadata": {
- "organizationCountryCode": "NO",
- "organizationNumber": 920970931,
- "endToEndId": "73300aef-d849-4872-b0c6-f44e07a841f3"
}, - "from": {
- "bban": 12341212345,
- "bic": "DNBANOKK",
- "contactInformation": {
- "name": "ZTL Payment Solution AS",
- "address": {
- "streetName": "Kristian IVs gate",
- "buildingNumber": 15,
- "city": "Oslo",
- "postCode": "0164",
- "country": "NO"
}
}, - "currency": "NOK",
- "country": "NO"
}, - "to": {
- "account": {
- "iban": "SE7250000000012341212345",
- "bban": 12341212345,
- "bic": "ESSESESS",
- "clearingCode": 1234
}, - "contactInformation": {
- "name": "ZTL Payment Solution AS",
- "address": {
- "streetName": "Eriksbergsgatan",
- "buildingNumber": 10,
- "city": "Sweden",
- "postCode": 11430,
- "country": "SE"
}
}
}, - "amount": {
- "amount": 1000,
- "currency": "SEK"
}, - "dueDate": "2023-01-15",
- "remittanceInformation": {
- "unstructured": "Payment for consulting services",
- "additionalInformation": [
- {
- "type": "Reason",
- "value": "string"
}
]
}, - "purposeCode": "S1008"
}Response samples
- 422
[- {
- "code": "InvalidFromAccount",
- "reason": "Invalid from account. From and to accounts must be different.",
- "path": ".from.bban"
}
]Payment Initiation
International payment quote request. Currently only available for selected customers. Please contact us if you're interested in testing this.
Authorizations:
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 | ||||||||||||||||||||
| |||||||||||||||||||||
required | object Information about the debtor | ||||||||||||||||||||
| |||||||||||||||||||||
required | object Information about the creditor | ||||||||||||||||||||
| |||||||||||||||||||||
required | object The amount and currency for the quote | ||||||||||||||||||||
| |||||||||||||||||||||
| 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 | ||||||||||||||||||||
| |||||||||||||||||||||
| 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
- Payload
{- "metadata": {
- "organizationCountryCode": "NO",
- "organizationNumber": 920970931,
- "endToEndId": "73300aef-d849-4872-b0c6-f44e07a841f3"
}, - "from": {
- "bban": 12341212345,
- "bic": "DNBANOKK",
- "contactInformation": {
- "name": "ZTL Payment Solution AS",
- "address": {
- "streetName": "Kristian IVs gate",
- "buildingNumber": 15,
- "city": "Oslo",
- "postCode": "0164",
- "country": "NO"
}
}, - "currency": "NOK",
- "country": "NO"
}, - "to": {
- "account": {
- "iban": "SE7250000000012341212345",
- "bban": 12341212345,
- "bic": "ESSESESS",
- "clearingCode": 1234
}, - "contactInformation": {
- "name": "ZTL Payment Solution AS",
- "address": {
- "streetName": "Eriksbergsgatan",
- "buildingNumber": 10,
- "city": "Sweden",
- "postCode": 11430,
- "country": "SE"
}
}
}, - "amount": {
- "amount": 1000,
- "currency": "SEK"
}, - "dueDate": "2023-01-15",
- "remittanceInformation": {
- "unstructured": "Payment for consulting services",
- "additionalInformation": [
- {
- "type": "Reason",
- "value": "string"
}
]
}, - "purposeCode": "S1008"
}Response samples
- 200
- 422
{- "quoteId": "d6f06bfe-4830-4358-b483-c24c66cfb431",
- "endToEndId": "7c628b2e-9094-4bf8-af23-1d517c6fc4f5",
- "requestedAmount": {
- "amount": 1000,
- "currency": "SEK"
}, - "costAmount": {
- "amount": 1034.62,
- "currency": "NOK"
}, - "exchangeRate": 1.0346,
- "quoteExpiryTime": "2023-01-15T09:32:00+01:00",
- "referenceCode": "ZTL-d6f06bfe",
- "intermediaryAccount": {
- "account": {
- "iban": "SE7250000000012341212345",
- "bban": 12341212345,
- "bic": "ESSESESS",
- "clearingCode": 1234
}, - "contactInformation": {
- "name": "ZTL Payment Solution AS",
- "address": {
- "streetName": "Eriksbergsgatan",
- "buildingNumber": 10,
- "city": "Sweden",
- "postCode": 11430,
- "country": "SE"
}
}
}
}Payment Confirmation
International payment confirmation. Currently only available for selected customers. Please contact us if you're interested in testing this.
Authorizations:
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
- 200
- 400
{- "paymentId": "0db94e47-858c-4486-a0e9-a453e4da025d",
}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:
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
- 200
- 400
{- "paymentId": "0db94e47-858c-4486-a0e9-a453e4da025d",
}Payment Status
International payment status inquiry. Currently only available for selected customers. Please contact us if you're interested in testing this.
Authorizations:
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
- 200
{- "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:
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
- 400
{- "message": "Payment not found.",
- "correlationId": "7757cdcb-128f-41ba-b3a6-58722e56b0f8"
}FX can either be used with or without bank integration. For bank integration, please see Flow for Currency CrossBorder transaction with bank integration
The partner is responsible to handle the domestic bank integration, or present the required payment instructions for domestic transaction to the user.
Cross-border payment requirements for receiving country
Country payment requirements
Authorizations:
path Parameters
| country required | string 2-letters country code |
Responses
Response samples
- 200
{- "countryCode": "SE",
- "countryName": "Sweden",
- "localCurrency": "NOK",
- "acceptedCurrencies": [
- "EUR"
], - "supportedBankAccountFormats": [
- {
- "type": "iban"
}
], - "paymentRequirements": [
- {
- "type": "additionalRemittanceInformationRequired",
- "description": "string",
- "requirementType": "PurposeCode",
- "pattern": "string",
- "validCodes": [
- {
- "code": "string",
- "description": "string"
}
], - "painArrayIndex": 0
}
]
}