Skip to content
ZTLDeveloper Portal

Payroll initiation

POST
/api/v2/payroll
Code sample: Shell / cURL
curl --request POST \
  --url https://api.ztlpay.io/api/v2/payroll \
  --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 '{ "from": { "account": { "bban": 97105048304 }, "name": "ZTL Payment Solution AS", "organizationNumber": 920970931 }, "transactions": [ { "metadata": { "endToEndId": "71a2e752-8b71-446f-b9e9-b19bfb70becb" }, "name": "Ola Nordmann", "account": { "bban": 97105048304 }, "amount": { "amount": "1000.50", "currency": "NOK" }, "remittanceInformation": { "type": "message", "value": "Payment for invoice 12345" } } ], "dueDate": "2024-01-15", "purposeCode": "SALA" }'

Initiates a new payroll, and returns a status for successful requests.

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
from
required

Account information for debtor

object
account
required
object
bban
required

A valid bban from one of the accounts on the consent.

string
Example
97105048304
name
required

The name of the organization making the payroll

string
Example
ZTL Payment Solution AS
organizationNumber

Organization number for the company

string
Example
920970931
transactions
required

A List of transactions for each individual payout in the payroll

Array<object>
object
metadata
required

Metadata for a single transaction

object
endToEndId
required

Identifier for the single transaction

string
Example
71a2e752-8b71-446f-b9e9-b19bfb70becb
name
required

The name of the receiver

string
Example
Ola Nordmann
account
required

A receiver account

object
bban
required

A valid bban from one of the accounts on the consent.

string
Example
97105048304
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
remittanceInformation
required
Any of:

Remittance information, either OCR or Text message

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

Message for receiver

string
Example
Payment for invoice 12345
dueDate
required

The due date for the payroll

string format: date, ISO-8601
Example
2024-01-15
purposeCode
required

Purpose code for payroll

string
Allowed values: SALA

Responses

Section titled “Responses”

200

Section titled “200”

Payroll initiated successfully

Media typeapplication/json
object
payrollId
required

Used for approval, cancellation, and status check

string format: uuid
transactions
required

Unsigned will be the status unless the account has some other rules

Array<object>
object
endToEndId
required

Same identifier as when creating a transaction

string
timestamp
required

The timestamp of the most recent internal update to the payroll status.

string
payrollStatus
required
  • Unsigned The user must approve the payroll.
  • InProgress The transaction is ongoing.
  • Completed The transaction/salary has been paid out.
  • Rejected The transaction has been rejected.
  • Cancelled The transaction has been cancelled.
  • CustomerActionRequired The payroll requires further action from the user.
string
Allowed values: Unsigned InProgress Completed Rejected Cancelled CustomerActionRequired
payrollStatusReason
  • PartlySigned Indicates that the payments needs additional signing. This requirement may be set up for the bank account.
  • SmsConfirmationRequired The user needs additional confirmation with responding SMS received. Only used by a few banks
  • InsufficientFunds The payment has been stopped by the bank due to lack of funds
string
Allowed values: PartlySigned SmsConfirmationRequired InsufficientFunds
Example
{
  "payrollId": "7c628b2e-9094-4bf8-af23-1d517c6fc4f5",
  "transactions": [
    {
      "timestamp": "2025-12-30 06:43:45.569610 +00:00",
      "payrollStatus": "Unsigned",
      "payrollStatusReason": "PartlySigned"
    }
  ]
}

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

Input validation fails

Media typeapplication/json
Array<object>
object
code

The error code

string
Allowed values: InvalidDueDate InvalidAmount InvalidBBAN InvalidRequest InvalidCharacters SenderNameTooLong RecipientNameTooLong InvalidAccountNumber InvalidRemittanceInfo
reason

The underlying reason for the error

string
path

Path from request body where the validation failed

string
Example
[
  {
    "code": "InvalidDueDate",
    "reason": "Due date cannot be in the past",
    "path": ".dueDate"
  }
]

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