Domestic payment initiation
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": "fik", "paymentType": "TYPE_01", "message": "Message for receiver", "ocr": 0, "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.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”Example
3a797348-ef0c-4f52-b821-fdfcdb98c4d9A valid consentId
Example
192.158.1.38AAA 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.
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.0Request Body
Section titled “Request Body”object
Metadata for the payment
object
An ID that can be used to identify the payment
Example
73300aefd8494872b0c6f44e07a841f3Account information for debtor
object
object
The name of the organization
Example
ZTL Payment Solution ASPhone number for the organization
Example
+4740000858Address information for payee
object
Street name
Example
AkersgataBuilding number
Example
32City or town name
Example
OsloPost code
Example
0180Country
Example
NOCurrency on from account
Example
NOKOrganization number for the company
Example
920970931Account information for creditor
object
object
Account number
Example
97105048304object
Example
SE7250000000012341212345object
Example
12345678Swedish giro, used for either BankGiro or PlusGiro. Requires RemittanceInformation of either message (invoiceRef) or ocr (giroOcrReference)
object
Reference to a Swedish BankGiro or PlusGiro account
Example
123-4567object
The name of the organization
Example
ZTL Payment Solution ASPhone number for the organization
Example
+4740000858Address information for payee
object
Street name
Example
AkersgataBuilding number
Example
32City or town name
Example
OsloPost code
Example
0180Country
Example
NOAmount and currency to be paid
object
Amount to be paid
Example
1000.50The currency the amount is specified in
Example
NOKThe due date for the payment
Example
2024-01-15Remittance information, either OCR or Text message
RemittanceInformationMessageText message, will be visible to receiver. Typically order number or description for paymentRemittanceInformationOcrOCR must be used if the receiving account is OCR account.RemittanceInformationFikFIK, only used in Denmark
object
Message for receiver
Example
Payment for invoice 12345Reference 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.
Remittance information, either OCR or Text message
RemittanceInformationMessageText message, will be visible to receiver. Typically order number or description for paymentRemittanceInformationOcrOCR must be used if the receiving account is OCR account.RemittanceInformationFikFIK, only used in Denmark
object
Please use ‘ocr’, ‘kid’ are deprecated
Example
24646Reference 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.
Remittance information, either OCR or Text message
RemittanceInformationMessageText message, will be visible to receiver. Typically order number or description for paymentRemittanceInformationOcrOCR must be used if the receiving account is OCR account.RemittanceInformationFikFIK, only used in Denmark
object
Example
Message for receiverExample
0Reference 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.
Purposecode for payment
Responses
Section titled “Responses”Payment initiated successfully
object
Used for approval and status check
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
UnsignedThe user must approve the transaction.InProgressThe payment is ongoing.CompletedThe payment has been completed by the bank.RejectedThe bank rejected the payment.CancelledThe payment has been cancelled.CustomerActionRequiredThe payment requires further action from the user. See statusReason for details.
PartlySignedIndicates that the payments needs additional signing. This requirement may be set up for the bank account.SmsConfirmationRequiredThe user needs additional confirmation with responding SMS received. Only used by a few banksInsufficientFundsThe payment has been stopped by the bank due to lack of funds
Payment status reason, unmapped reason text from bank.
Timestamp when the status was fetched from bank
Example
{ "paymentId": "7c628b2e-9094-4bf8-af23-1d517c6fc4f5", "paymentStatus": { "status": "Unsigned", "statusReason": "PartlySigned", "timestamp": "2024-03-19T09:34:57.657733682+01:00" }}Bad Request
object
INVALID_CONSENTConsent is invalidAUTHENTICATION_TEMPORARY_UNAVAILABLEAuthentication service is temporary unavailable, most likely due to user already has started another concurrent authentication processUNSUPPORTED_PRODUCT_BY_BANKProduct is not supported by bankINVALID_OCROCR is either missing or invalid, or invalid OCR agreementACCESS_DENIEDPSU does not have access to resource. Ensure debtorAccount is correct and user have payment access to account.
Unique RequestId, please provide this Id in case of support requests
The underlying reason for the error
Example
{ "failure": "INVALID_CONSENT", "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9", "message": "Invalid Bban"}Forbidden
object
Unique RequestId, please provide this Id in case of support requests
The underlying reason for the error
Example
{ "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9", "message": "Invalid account"}Headers
Section titled “Headers”Unique RequestId, please provide this Id in case of support requests
Example
3a797348-ef0c-4f52-b821-fdfcdb98c4d9Not found
object
Unique RequestId, please provide this Id in case of support requests
The underlying reason for the error
Example
{ "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9", "message": "Invalid account"}Headers
Section titled “Headers”Unique RequestId, please provide this Id in case of support requests
Example
3a797348-ef0c-4f52-b821-fdfcdb98c4d9Conflict
object
Unique RequestId, please provide this Id in case of support requests
The underlying reason for the error
Example
{ "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9", "message": "Invalid account"}Headers
Section titled “Headers”Unique RequestId, please provide this Id in case of support requests
Example
3a797348-ef0c-4f52-b821-fdfcdb98c4d9Input validation fails
object
The error code
The underlying reason for the error
Path from request body where the validation failed
Example
[ { "code": "InvalidBBAN", "reason": "Due date cannot be in the past", "path": ".dueDate" }]Internal server error
object
Unique RequestId, please provide this Id in case of support requests
The underlying reason for the error
Example
{ "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9", "message": "Invalid account"}Headers
Section titled “Headers”Unique RequestId, please provide this Id in case of support requests
Example
3a797348-ef0c-4f52-b821-fdfcdb98c4d9Service unavailable
object
Unique RequestId, please provide this Id in case of support requests
The underlying reason for the error
Example
{ "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9", "message": "Invalid account"}Headers
Section titled “Headers”Unique RequestId, please provide this Id in case of support requests
Example
3a797348-ef0c-4f52-b821-fdfcdb98c4d9