Skip to content
ZTLDeveloper Portal

Initiate cross-border payment

POST
/api/v2/payments/cross-border
Code sample: Shell / cURL
curl --request POST \
  --url https://api.ztlpay.io/api/v2/payments/cross-border \
  --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": "example" }, "from": { "account": { "type": "bban", "bic": "ESSESESS", "bban": 12341212345 }, "contactInformation": { "name": "ZTL Payment Solution AS", "address": { "streetName": "Akersgata", "buildingNumber": 32, "city": "Oslo", "postCode": "0180", "country": "NO" }, "telephoneNumber": "+4740000858" }, "currency": "NOK", "organizationNumber": 920970931 }, "to": { "account": { "type": "bban", "bic": "ESSESESS", "bban": 12341212345, "clearingCode": 1234 }, "contactInformation": { "name": "ZTL Payment Solution AS", "address": { "streetName": "Akersgata", "buildingNumber": 32, "city": "Oslo", "postCode": "0180", "country": "NO" } } }, "amount": { "amount": "1000.50", "currency": "NOK" }, "dueDate": "2026-04-15", "remittanceInformation": { "message": "example", "additionalInformation": [ { "type": "TaxCode", "value": "example" } ], "debtorReference": "example" }, "regulatoryReporting": { "code": "14", "information": "example" } }'

Initiates a cross-border payment, this includes all transactions involving currency accounts. If the transaction requires exchange it will result in a psd2 domestic payment to ZTL’s client account, these payment must be signed within deadline (2 or 5 minutes), if not it gets automatically cancelled. Payments that do not require exchange will go through the bank as cross-border payments.

We request that when a cross-border payment is initiated and due date is today or tomorrow (if initiated after 16:00) that you give user a warning if balance is less than value of the payment. Reason for this warning is to remind those who are lacking funds that they do not have funds and to avoid the payment being delayed or in worst case cancelled.

See Country and Currencies endpoint supported countries, currencies and constraints.

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
metadata
required
object
endToEndId
required

External EndToEndId for the payment

string
from
required
object
account
required
object
type
required
string
Allowed values: bban
bic
required

Bank Identification Code

string
Example
ESSESESS
bban
required

Bank Account number in Bban format

string
Example
12341212345
contactInformation
required
object
name
required

The name of the organization.

Maximum length depends on whether the payment includes currency exchange:

  • Without currency exchange: check debtor bank maxInformationFieldLength requirements
  • With currency exchange: 70 characters
string
Example
ZTL Payment Solution AS
address
required

Address information for payee

object
streetName
required

Street name

string
Example
Akersgata
buildingNumber
required

Building number

string
Example
32
city
required

City or town name

string
Example
Oslo
postCode
required

Post code

string
Example
0180
country
required

Country

string format: ISO 3166-1
Example
NO
telephoneNumber

Phone number for the organization

string
Example
+4740000858
currency
required

Sender accounts Currency

string
Example
NOK
organizationNumber

Organization number for the company

string
Example
920970931
to
required
object
account
required
Any of:
object
type
required
string
Allowed values: bban
bic
required

Bank Identification Code

string
Example
ESSESESS
bban
required

Bank Account number in Bban format

string
Example
12341212345
clearingCode

Code required for payments to certain countries

string
Example
1234
contactInformation
required
object
name
required

The name of the organization.

Maximum length depends on whether the payment includes currency exchange:

  • Without currency exchange: check debtor bank maxInformationFieldLength requirements
  • With currency exchange: 70 characters
string
Example
ZTL Payment Solution AS
address
required

Address information for payee

object
streetName
required

Street name

string
Example
Akersgata
buildingNumber
required

Building number

string
Example
32
city
required

City or town name

string
Example
Oslo
postCode
required

Post code

string
Example
0180
country
required

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 psd2 transaction from user account to ZTL client account. Payout to creditor account are usually 2 business days later

string format: date
remittanceInformation
required
object
message
required
string
additionalInformation
Array<object>
object
type

Type of additional information. Must be compliant with receiving country rules

  • Reason Text to describe the reason for payment
  • Purpose A valid PurposeCode of the payment
  • TaxCode Receiver Tax code
string
Allowed values: TaxCode Reason Purpose
Example
Reason
value

Value of the property

string
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
regulatoryReporting

Information used for regulatory reporting, only applicable in Norway and Sweden. Required for payments above 100 000 NOK in Norway, and 150 000 SEK in Sweden.

object
code
required

Code used for regulatory reporting

string
Example
14
information

Information for regulatory reporting, only applicable in Norway

string

Responses

Section titled “Responses”

200

Section titled “200”

Initiated cross-border payment

Media typeapplication/json
object
paymentId
required
string
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
costAmount

Amount and currency to be paid

object
amount
required

Amount to be paid

string
currency
required

The currency the amount is specified in

string
exchangeRate

The exchange rate per single unit

string
quoteExpiryTime

Expiry time for quote, the payment may be automatically cancelled by ZTL if it’s not signed before this deadline

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
{
  "paymentStatus": {
    "status": "Unsigned",
    "statusReason": "PartlySigned",
    "timestamp": "2024-03-19T09:34:57.657733682+01:00"
  },
  "costAmount": {
    "amount": "1000.50",
    "currency": "NOK"
  },
  "exchangeRate": 1.0346,
  "quoteExpiryTime": "2023-01-15T09:32:00+01:00",
  "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
  • MAX_AMOUNT_EXCEEDED Max amount exceeded for currency with due date in future, change due-date to today
  • SERVICE_CLOSED Service is currently closed
  • UNSUPPORTED_DUE_DATE Due date is not supported for the currency/due-date pair
  • 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
  • ACCESS_DENIED PSU does not have access to resource. Ensure debtorAccount is correct and user have payment access to account.
string
Allowed values: MAX_AMOUNT_EXCEEDED SERVICE_CLOSED UNSUPPORTED_DUE_DATE INVALID_CONSENT AUTHENTICATION_TEMPORARY_UNAVAILABLE UNSUPPORTED_PRODUCT_BY_BANK 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": "MAX_AMOUNT_EXCEEDED",
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Max amount exceeded for currency with due date in future, change due-date to today"
}

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”

Input validation fails

Media typeapplication/json
Array<object>
object
code

The error code

string
Allowed values: InvalidRequest InvalidCreationTime InvalidDueDate 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
Example
[
  {
    "code": "InvalidRequest",
    "reason": "Invalid account",
    "path": ".from.account"
  }
]

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