Skip to content
ZTLDeveloper Portal

Payment Initiation

POST
/api/fx/payments
Code sample: Shell / cURL
curl --request POST \
  --url https://api.ztlpay.io/api/fx/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "metadata": { "organizationCountryCode": "NO", "organizationNumber": 920970931, "endToEndId": "73300aef-d849-4872-b0c6-f44e07a841f3" }, "from": { "bban": 12341212345, "bic": "DNBANOKK", "contactInformation": { "name": "ZTL Payment Solution AS", "address": { "streetName": "Kristian IVs gate", "buildingNumber": 15, "city": "Oslo", "postCode": "0164", "country": "NO" } }, "currency": "NOK", "country": "NO" }, "to": { "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" } }, "currency": "SEK" }, "amount": { "amount": "1000.50", "currency": "SEK" }, "dueDate": "2023-01-15", "remittanceInformation": { "unstructured": "Payment for consulting services", "additionalInformation": [ { "type": "TaxCode", "value": "example" } ] }, "purposeCode": "S1008" }'

International payment quote request

We request that when a fx 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 before calling confirm. 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.

Authorizations

Section titled “Authorizations”

Request Body

Section titled “Request Body”
Media typeapplication/json
object
metadata
required

Metadata for quote request

object
organizationCountryCode
required

Country

string format: ISO 3166-1
Example
NO
organizationNumber
required

The organization number of the company initiating the payment

string
Example
920970931
endToEndId
required

An ID that can be used to identify the payment

string
Example
73300aef-d849-4872-b0c6-f44e07a841f3
from
required

Information about the debtor

object
bban
required

Basic Bank Account Number

string
Example
12341212345
bic
required

Bank Identification Code

string
Example
DNBANOKK
contactInformation
required

Debtor contact information

object
name
required

The name of the organization making the payment

string
Example
ZTL Payment Solution AS
address
required

The address of the organization making the payment

object
streetName
required

Street name

string
Example
Kristian IVs gate
buildingNumber
required

Building number

string
Example
15
city
required

City or town name

string
Example
Oslo
postCode
required

Post code

string
Example
0164
country
required

Country

string format: ISO 3166-1
Example
NO
currency
required

The base(funding) currency for the payment

string
Example
NOK
country
required

The country that the payment is being initiated from

string format: ISO 3166-1
Example
NO
to
required

Information about the creditor

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
Example
SE7250000000012341212345
bban

Basic Bank Account Number

string
Example
12341212345
bic
required

Bank Identification Code

string
Example
ESSESESS
clearingCode

Code required for payments to certain countries

string
Example
1234
contactInformation
required

Creditor contact information

object
name
required

The name of the organization making the payment

string
Example
ZTL Payment Solution AS
address
required

The address of the organization making the payment

object
streetName
required

Street name

string
Example
Eriksbergsgatan
buildingNumber
required

Building number

string
Example
10
city
required

City or town name

string
Example
Sweden
postCode
required

Post code

string
Example
11430
country
required

Country

string format: ISO 3166-1
Example
SE
currency

The payout currency for the payment (only used for SELL deal type)

string
Example
SEK
amount
required

The amount and currency for the quote

object
amount
required

The amount to get a quote for

string
Example
1000.50
currency
required

The currency the amount is specified in

string
Example
SEK
dueDate
required

The due date for the payment. NOTE: there are limitations on due date in the further

string format: date, ISO-8601
Example
2023-01-15
remittanceInformation
required

Remittance information

object
unstructured
required

Message for receiver

string
Example
Payment for consulting services
additionalInformation
Array<object>
object
type
required

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
required

Value of the property

string
purposeCode

A code stating the purpose of the payment. (Required by some countries). Deprecated - use Information.RemittanceInformation.AdditionalInformation (type - Purpose) instead

string
Example
S1008

Responses

Section titled “Responses”

200

Section titled “200”

Successfully acquired foreign exchange quote

Media typeapplication/json
object
quoteId
required

The quote ID to use for booking

string format: UUID
endToEndId
required

An ID that can be used to identify the payment

string
requestedAmount
required

The amount and currency that will be paid out

object
amount
required

The amount to get a quote for

string
currency
required

The currency the amount is specified in

string
costAmount
required

The amount and currency of the resulting cost (funding) for the quote

object
amount
required

The amount it will cost to buy the requested / quoted amount

string
currency
required

The currency the amount is specified in

string
exchangeRate
required

The exchange rate per single unit

string
quoteExpiryTime
required
string format: datetime, ISO-8601
referenceCode
required

The reference code to add to the payment’s unstructured remittance info

string
intermediaryAccount
required

The account to deposit funding amount to when initiating payment

object
account
required

Account information for funding client account

object
iban
required

International Bank Account Number

string
bban
required

Basic Bank Account Number

string
bic
required

Bank Identification Code

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
{
  "quoteId": "d6f06bfe-4830-4358-b483-c24c66cfb431",
  "endToEndId": "7c628b2e-9094-4bf8-af23-1d517c6fc4f5",
  "requestedAmount": {
    "amount": "1000.50",
    "currency": "SEK"
  },
  "costAmount": {
    "amount": 1034.62,
    "currency": "NOK"
  },
  "exchangeRate": 1.0346,
  "quoteExpiryTime": "2023-01-15T09:32:00+01:00",
  "referenceCode": "ZTL-d6f06bfe",
  "intermediaryAccount": {
    "account": {
      "iban": "SE7250000000012341212345",
      "bban": 12341212345,
      "bic": "CITIXXXX"
    },
    "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
code

The parsing error type

string
reason

The underlying reason for the error

string
path

Path to the related input param with parsing error

string
Example
{
  "code": "InvalidJsonRequest",
  "reason": "Malformed request body",
  "path": ".from.bban"
}

403

Section titled “403”

Forbidden

Media typetext/plain
string
Example
Company is not onboarded

422

Section titled “422”

Validation failed

Media typeapplication/json
Array<object>
object
code

The validation error code.

Possible values:

  • InvalidCreationTime: Payment initiation is not supported during weekends/bank holidays
  • InvalidDueDate: Available due date range is dependent on initiation time
  • InvalidFromAccount: Sender’s and recipient’s account numbers cannot have the same value
  • InvalidFromCountry: Provided sender’s country does not match provided sender’s BIC
  • InvalidToAddress: One of the recipient’s address fields are invalid (specified in the reason field)
  • InvalidToAccount: IBAN and BBAN values cannot be equal
  • InvalidBbanOrIban: Either IBAN or BBAN must be provided for the recipient account
  • InvalidIban: IBAN is either missing or invalid
  • IbanBicMismatch: The IBAN does not match the provided BIC
  • InvalidBIC: BIC is either missing or invalid
  • InvalidBeneficiaryCountry: Recipient’s country is not supported
  • InvalidAmount: Requested amount exceeds the limit amount of the currency for the chosen due date
  • InvalidQuoteCurrencyScale: Invalid scale for requested currency
  • InvalidCurrency: Given currency is not accepted by the recipient’s country
  • CurrencyPairMismatch: Funding currency and requested currency cannot be the same
  • InvalidRecipientInfo: Recipient country specific payment requirements are not met (check /api/country/{country}/paymentrequirement for specifics)
  • InvalidRemittanceInformation: (Additional) remittance information is missing or invalid
string
Allowed values: InvalidCreationTime InvalidDueDate InvalidFromAccount InvalidFromCountry InvalidToAddress InvalidToAccount InvalidBbanOrIban InvalidIban IbanBicMismatch InvalidBIC InvalidBeneficiaryCountry InvalidAmount InvalidQuoteCurrencyScale InvalidCurrency CurrencyPairMismatch InvalidRecipientInfo InvalidRemittanceInformation
reason

The underlying reason for the error

string
path

Path to the related input param with validation error

string
Example
[
  {
    "code": "InvalidCreationTime",
    "reason": "InvalidToAccount",
    "path": ".from.bban"
  }
]