Skip to content

Domestic payment initiation

POST
/api/v2/payments
Code sample: Shell / cURL
curl --request POST \
--url https://api.ztlpay.io/api/v2/payments \
--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 '{ "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": "message", "value": "Payment for invoice 12345", "debtorReference": "example" }, "purposeCode": "SUPP" }'

Initiates a new domestic payment, and returns status. Normally the status will be Unsigned, indicating that the payment needs to be approved before executed. Some payments do not require signing, this is dependent on the bank account configuration. This endpoint is supported if the bank contains the product PAYMENT_DOMESTIC.

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
Media typeapplication/json
object
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

Bban is recommended when available, support for iban varies.

Any of:
PaymentAccountBban
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
  • PaymentAccountBban Domestic account number
  • PaymentAccountIban Iban account number (support for iban varies, bban is recommended for domestic payments)
  • PaymentAccountFik Fik number, only used in Denmark
  • SwedishGiro Swedish Giro, only used in Sweden
Any of:
PaymentAccountBban
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

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
Any of:
RemittanceInformationMessage
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

Payment initiated successfully

Media typeapplication/json
object
paymentId
required

Used for approval and status check

string format: uuid
paymentStatus
required

The initial payment status indicates if the payment was accepted, and if it needs to be signed before it will be executed in the bank

object
status
required
  • Unsigned The user must approve the transaction.
  • InProgress The payment is ongoing.
  • Completed The payment has been completed by the bank.
  • Rejected The bank rejected the payment.
  • Cancelled The payment has been cancelled.
  • CustomerActionRequired The payment requires further action from the user. See statusReason for details.
string
Allowed values: Unsigned InProgress Completed Rejected Cancelled CustomerActionRequired
statusReason
  • 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
statusReasonText

Payment status reason, unmapped reason text from bank.

string
timestamp
required

Timestamp when the status was fetched from bank

string

Example

{
"paymentId": "7c628b2e-9094-4bf8-af23-1d517c6fc4f5",
"paymentStatus": {
"status": "Unsigned",
"statusReason": "PartlySigned",
"timestamp": "2024-03-19T09:34:57.657733682+01:00"
}
}

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

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"
}
ztl-request-id
string format: uuid

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

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

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"
}
ztl-request-id
string format: uuid

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

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

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"
}
ztl-request-id
string format: uuid

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

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

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
reason

The underlying reason for the error

string
path

Path from request body where the validation failed

string

Example

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

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"
}
ztl-request-id
string format: uuid

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

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

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"
}
ztl-request-id
string format: uuid

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

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