Skip to content
ZTLDeveloper Portal

Initiate bulk payment(s)

POST
/api/v2/payments/bulk
Code sample: Shell / cURL
curl --request POST \
  --url https://api.ztlpay.io/api/v2/payments/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'PSU-IP-Address: 192.158.1.38' \
  --header 'PSU-User-Agent: Mozilla/5.0 (Windows NT 10.0; …) Gecko/20100101 Firefox/63.0' \
  --header 'consent-id: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9' \
  --data '{ "payments": [ { "type": "domestic", "metadata": { "endToEndId": "73300aefd8494872b0c6f44e07a841f3" }, "from": { "account": { "type": "bban", "bban": 97105048304 }, "contactInformation": { "name": "ZTL Payment Solution AS", "telephoneNumber": "+4740000858", "address": { "streetName": "Akersgata", "buildingNumber": "32", "city": "Oslo", "postCode": "0180", "country": "NO" } }, "currency": "NOK", "organizationNumber": 920970931 }, "to": { "account": { "type": "bban", "bban": 97105048304 }, "contactInformation": { "name": "ZTL Payment Solution AS", "telephoneNumber": "+4740000858", "address": { "streetName": "Akersgata", "buildingNumber": "32", "city": "Oslo", "postCode": "0180", "country": "NO" } } }, "amount": { "amount": "1000.50", "currency": "NOK" }, "dueDate": "2024-01-15", "remittanceInformation": { "type": "fik", "paymentType": "TYPE_01", "message": "Message for receiver", "ocr": 0, "debtorReference": "example" }, "purposeCode": "SUPP" } ], "callbackUrl": "https://www.google.com" }'

Initiates a list of payments with started approval/signing. This endpoint is exclusively supported for banks that do not support single payments/approval - see banks supported products (PAYMENT_BULK). This is currently only supported by Danske Bank and Handelsbanken Sweden. The response gives an id for the bulk status, which must be used in fetch status for bulk endpoint. This endpoint gives Id for the payments, which again can be used to fetch payment status. In some cases, the payment Ids are only available after the approval/signing process has completed.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
consent-id
required
string format: uuid
Example
3a797348-ef0c-4f52-b821-fdfcdb98c4d9

A valid consentId

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

The forwarded Agent header field of the HTTP request between PSU and TPP.

Example
Mozilla/5.0 (Windows NT 10.0; …) Gecko/20100101 Firefox/63.0

Request Body

Section titled “Request Body”
Media typeapplication/json
object
payments
required
Array
>= 1 items
One of:
Domestic payment
object
type
string
Allowed values: domestic
metadata
required

Metadata for the payment

object
endToEndId
required

An ID that can be used to identify the payment

string
Example
73300aefd8494872b0c6f44e07a841f3
from
required

Account information for debtor

object
account
required
Any of:
object
type
required
string
Allowed values: bban
bban
required

Account number

string
Example
97105048304
contactInformation
required
object
name
required

The name of the organization

string
Example
ZTL Payment Solution AS
telephoneNumber

Phone number for the organization

string
Example
+4740000858
address

Address information for payee

object
streetName

Street name

string
Example
Akersgata
buildingNumber

Building number

string
Example
32
city

City or town name

string
Example
Oslo
postCode

Post code

string
Example
0180
country

Country

string format: ISO 3166-1
Example
NO
currency
required

Currency on from account

string
Example
NOK
organizationNumber

Organization number for the company

string
Example
920970931
to
required

Account information for creditor

object
account
required
Any of:
object
type
required
string
Allowed values: bban
bban
required

Account number

string
Example
97105048304
contactInformation
required
object
name
required

The name of the organization

string
Example
ZTL Payment Solution AS
telephoneNumber

Phone number for the organization

string
Example
+4740000858
address

Address information for payee

object
streetName

Street name

string
Example
Akersgata
buildingNumber

Building number

string
Example
32
city

City or town name

string
Example
Oslo
postCode

Post code

string
Example
0180
country

Country

string format: ISO 3166-1
Example
NO
amount
required

Amount and currency to be paid

object
amount
required

Amount to be paid

string
Example
1000.50
currency
required

The currency the amount is specified in

string
Example
NOK
dueDate
required

The due date for the payment

string format: date, ISO-8601
Example
2024-01-15
remittanceInformation
Any of:

Remittance information, either OCR or Text message

  • RemittanceInformationMessage Text message, will be visible to receiver. Typically order number or description for payment
  • RemittanceInformationOcr OCR must be used if the receiving account is OCR account.
  • RemittanceInformationFik FIK, only used in Denmark
object
type
required
string
Allowed values: message
value
required

Message for receiver

string
Example
Payment for invoice 12345
debtorReference

Reference text or message intended for display to the debtor only. It can be used to provide debtor-facing payment details or context. Availability depends on bank support and is included only when accepted by the receiving institution.

string
purposeCode

Purposecode for payment

string
Allowed values: SUPP TAXS SALA VATX OTHR
callbackUrl
required

Sca callback url for redirect authentication

string
Example
https://www.google.com

Responses

Section titled “Responses”

200

Section titled “200”

Bulk created successfully

Media typeapplication/json
object
id
required

ID of bulk

string format: uuid
sca

There is no guarantee that the used sca approach used by bank matches the preferred sca approach from request.

  • redirect For redirect, the end user must use the redirect url to start the authentication process
  • qr The QR image has to be presented to the end user, who has to scan the image with bank authentication app. The qr image needs to be refreshed every second, see approval status for refreshed QR image. Only used in Sweden
object
One of:
redirect
object
type
required

Redirect link to redirect authorization flow. After the redirect, the url will contain the query parameter status, with the possible values [success, rejected, cancelled]

string
Allowed values: redirect
url
required

Url to start authorization redirect flow

string
transactions
Array<object>
object
id

Id of the transaction

string format: uuid
endToEndId
required

EndToEndId as used in initial request

string
costAmount

Cost amount

object
amount
required

Amount to be paid

string
currency
required

The currency the amount is specified in

string
exchangeRate

The exchange rate

number
quoteExpiryTime

Expiry time for quote

string format: datetime, ISO-8601
intermediaryAccount

The Client account for the funding domestic psd2 transaction related to the payment. Account owned by ZTL.

object
account
required

Account information for creditor. Required fields depend on creditorCountry, but bban or iban should always be present.

object
iban

International Bank Account Number

string
bban

Basic Bank Account Number

string
bic

Bank Identification Code

string
clearingCode

Code required for payments to certain countries

string
contactInformation
required

Creditor contact information

object
name
required

The name of the organization making the payment

string
address
required

The address of the organization making the payment

object
streetName
required

Street name

string
buildingNumber
required

Building number

string
city
required

City or town name

string
postCode
required

Post code

string
country
required

Country

string format: ISO 3166-1
Example
{
  "sca": {
    "type": "redirect",
    "url": "https://api.ztlpay.io/api/v2/consents/sca/redirect/start/6212d401-1785-4739-8843-55fe4eb9dad4"
  },
  "transactions": [
    {
      "costAmount": {
        "amount": "1000.50",
        "currency": "NOK"
      },
      "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"
          }
        }
      }
    }
  ]
}

400

Section titled “400”

Bad Request

Media typeapplication/json
object
failure
  • INVALID_CONSENT Consent is invalid
  • AUTHENTICATION_TEMPORARY_UNAVAILABLE Authentication service is temporary unavailable, most likely due to user already has started another concurrent authentication process
  • UNSUPPORTED_PRODUCT_BY_BANK Product is not supported by bank
  • INVALID_OCR OCR is either missing or invalid, or invalid OCR agreement
  • ACCESS_DENIED PSU does not have access to resource. Ensure debtorAccount is correct and user have payment access to account.
string
Allowed values: INVALID_CONSENT AUTHENTICATION_TEMPORARY_UNAVAILABLE UNSUPPORTED_PRODUCT_BY_BANK INVALID_OCR ACCESS_DENIED
ztlRequestId
required

Unique RequestId, please provide this Id in case of support requests

string format: uuid
message
required

The underlying reason for the error

string
Example
{
  "failure": "INVALID_CONSENT",
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Invalid Bban"
}

403

Section titled “403”

Forbidden

Media typeapplication/json
object
failure
string
Allowed values: COMPANY_DISABLED_FOR_INTERNATIONAL_PAYMENTS
ztlRequestId
required

Unique RequestId, please provide this Id in case of support requests

string format: uuid
message
required

The underlying reason for the error

string
Example
{
  "failure": "COMPANY_DISABLED_FOR_INTERNATIONAL_PAYMENTS",
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Invalid account"
}

404

Section titled “404”

Not found

Media typeapplication/json
object
ztlRequestId
required

Unique RequestId, please provide this Id in case of support requests

string format: uuid
message
required

The underlying reason for the error

string
Example
{
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Invalid account"
}

Headers

Section titled “Headers”
ztl-request-id
string format: uuid

Unique RequestId, please provide this Id in case of support requests

Example
3a797348-ef0c-4f52-b821-fdfcdb98c4d9

409

Section titled “409”

Conflict

Media typeapplication/json
object
ztlRequestId
required

Unique RequestId, please provide this Id in case of support requests

string format: uuid
message
required

The underlying reason for the error

string
Example
{
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Invalid account"
}

Headers

Section titled “Headers”
ztl-request-id
string format: uuid

Unique RequestId, please provide this Id in case of support requests

Example
3a797348-ef0c-4f52-b821-fdfcdb98c4d9

422

Section titled “422”

Bulk input validation fails

Media typeapplication/json
Array<object>
object
code

The error code

string
Allowed values: InvalidBBAN SenderNameTooLong RecipientNameTooLong InvalidAccountNumber InvalidAmount InvalidDueDate InvalidRemittanceInfo InvalidCharacters InvalidRequest InvalidBulkSize InvalidCreationTime IbanBicMismatch InvalidIbanFormat InvalidFromAccount InvalidBbanOrIban InvalidForwardAmount InvalidForwardCurrency InvalidQuoteCurrencyScale InvalidForwardExchangeServiceTime InvalidJsonRequest InvalidBeneficiaryCountry InvalidBIC InvalidToAddress
reason

The underlying reason for the error

string
path

Path for the error

string
endToEndId

End-to-end identifier of the payment that failed validation, when available

string
nullable
Example
[
  {
    "code": "InvalidBBAN",
    "reason": "EndToEndId must be unique within the same bulk",
    "path": ".payments",
    "endToEndId": "197102754228134604603270233998"
  }
]

500

Section titled “500”

Internal server error

Media typeapplication/json
object
ztlRequestId
required

Unique RequestId, please provide this Id in case of support requests

string format: uuid
message
required

The underlying reason for the error

string
Example
{
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Invalid account"
}

Headers

Section titled “Headers”
ztl-request-id
string format: uuid

Unique RequestId, please provide this Id in case of support requests

Example
3a797348-ef0c-4f52-b821-fdfcdb98c4d9

503

Section titled “503”

Service unavailable

Media typeapplication/json
object
ztlRequestId
required

Unique RequestId, please provide this Id in case of support requests

string format: uuid
message
required

The underlying reason for the error

string
Example
{
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Invalid account"
}

Headers

Section titled “Headers”
ztl-request-id
string format: uuid

Unique RequestId, please provide this Id in case of support requests

Example
3a797348-ef0c-4f52-b821-fdfcdb98c4d9