Guides

ISO Payments

The ISO Payments API allows users to initiate secure, structured payments by submitting payment instructions in JSON format from which an ISO 20022 pain.001 file is generated and uploaded to the online bank for authorization.

For requests to the PIS API, you need an access token with scope set to paymentinitiation corporate.

Domestic Payments

This guide will show you how to initiate a simple domestic corporate account-to-account transfer via ISO.

1. Create Payment

Endpoint

POST /iso/payments

http

Request Headers

Name	Type	Description
`X-Request-ID`	string	The ID of the request, unique to the call, as determined by the initiating party.
`X-BicFi`	string	The BIC of the bank to which the request is addressed.
`PSU-ID`	string	The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID.
`PSU-Corporate-ID`	string	The Corporate ID of the PSU when acting on behalf of an organization, e.g. Org. nummer for SE, KVK for NL.
`PSU-IP-Address`	string	The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU.

Request Body

Name	Type	Description
`instructedAmount`	object	The amount and currency of the money to be transferred.
`debtorAccount`	object	The account from which the payment will be debited.
`creditorName`	string	The full name of the payment recipient.
`creditorAccount`	object	The account to which the payment will be credited.
`creditorAgent`	string	The BIC of the payment recipient's bank.
`creditorAgentName`	string	The name of the payment recipient's bank.
`requestedExecutionDate`	string	The date when the payment is scheduled to be executed in ISO 8601 format, e.g. 2025-10-31.
`remittanceInformationUnstructured`	string	A free-text field for remittance information on the payment.
`debtorAccountMessage`	string	A personal message from the payer to themselves.

curl -X POST "https://api.openbankingplatform.com/iso/payments" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0..." \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 2e02a131-a35a-450f-a736-9a06086f3337" \
  -H "X-BicFi: ESSESESS" \
  -H "PSU-ID: 123456789001" \
  -H "PSU-Corporate-ID: 1234567890" \
  -H "PSU-IP-Address: 152.120.171.187" \
  -d '{
    "instructedAmount": {
      "currency": "SEK",
      "amount": "1230.50"
    },
    "debtorAccount": {
      "iban": "SE123456789000532811"
    },
    "creditorName": "John Doe",
    "creditorAccount": {
      "iban": "SE123456789000222333"
    },
    "creditorAgent": "HANDSESS", 
    "creditorAgentName": "Svenska Handelsbanken AB",
    "requestedExecutionDate": "2025-06-10",
    "remittanceInformationUnstructured": "Ref Number Merchant",
    "debtorAccountMessage": "Personal note"
    }'

bash

Response

{
    "transactionStatus": "RCVD",
    "paymentId": "a3cf0daa-6d43-4156-afd4-1d859ad448a8",
    "_links": {
        "confirmPayment": {
            "href": "/iso/payments/confirm"
        },
        "self": {
            "href": "/iso/payments/a3cf0daa-6d43-4156-afd4-1d859ad448a8"
        }
    }
}

json

2. Confirm Payment

Once the ISO payment is created, we confirm the payment to generate and upload a pain.001 file to the online bank. Multiple existing payments can be included in the file by specifying them in the paymentIds body parameter. In this guide, we will only include the payment we created in the previous step.

Endpoint

PUT /iso/payments/confirm

http

Request Headers

Name	Type	Description
`X-Request-ID`	string(uuid)	The ID of the request, unique to the call, as determined by the initiating party.
`X-BicFi`	string	The BIC of the bank to which the request is addressed.
`PSU-ID`	string	The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID.
`PSU-Corporate-ID`	string	The Corporate ID of the PSU when acting on behalf of an organization, e.g. Org. nummer for SE, KVK for NL.
`PSU-IP-Address`	string(ipv4)	The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU.

Request Body

Name	Type	Description
`paymentIds`	array	The IDs of the payments to include in the confirmation.
`batchBookingPreferred`	boolean	Indicates a preference to execute the payment as a batch booking when set to `true`.

curl -X PUT "https://api.openbankingplatform.com/iso/payments/confirm" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0..." \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: e26e0f4b-7fbd-4a23-8939-aa7e5275825c" \
  -H "X-BicFi: ESSESESS" \
  -H "PSU-ID: 123456789001" \
  -H "PSU-Corporate-ID: 1234567890" \
  -H "PSU-IP-Address: 152.120.171.187" \
  -d '{
    "paymentIds": [
        "a3cf0daa-6d43-4156-afd4-1d859ad448a8"
    ],
    "batchBookingPreferred": "false"
    }'

bash

Response

{
    "tppMessages": [
        {
            "category": "INFORMATION",
            "code": "FILE_UPLOADED",
            "text": "OPE20250609T1057016350301Z"
        }
    ]
}

json

3. Authorise Payment

After successfully confirming the payment, the user then needs to authorize the payment by logging into the online bank and signing the file.

4. Get Payment

Lastly, we check the status of the payment.

Endpoint

GET /iso/payments/{paymentId}

http

Path Parameters

Name	Type	Description
`paymentId`	string	The ID of the payment that was created.

Request Headers

Name	Type	Description
`X-Request-ID`	string(uuid)	The ID of the request, unique to the call, as determined by the initiating party.
`X-BicFi`	string	The BIC of the bank to which the request is addressed.
`PSU-ID`	string	The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID.
`PSU-Corporate-ID`	string	The Corporate ID of the PSU when acting on behalf of an organization, e.g. Org. nummer for SE, KVK for NL.
`PSU-IP-Address`	string(ipv4)	The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU.

curl -X GET "https://api.openbankingplatform.com/iso/payments/a3cf0daa-6d43-4156-afd4-1d859ad448a8" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0..." \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: c2ef85d1-dfc8-450d-b820-c90edc0f7de2" \
  -H "X-BicFi: ESSESESS" \
  -H "PSU-ID: 123456789001" \
  -H "PSU-Corporate-ID: 1234567890" \
  -H "PSU-IP-Address: 152.120.171.187"

bash

Response

{
    "transactionStatus": "ACSC"
}

json

Note: Payments can have a number of different statuses. Here, we want to check if the payment was rejected, in which case transactionStatus would have the value RJCT. If not, then we are done.

Swedish Giro Payments

This guide will show you how to initiate a Swedish Giro payment via ISO.

1. Create Payment

Endpoint

POST /iso/payments

http

Request Headers

Name	Type	Description
`X-Request-ID`	string(uuid)	The ID of the request, unique to the call, as determined by the initiating party.
`X-BicFi`	string	The BIC of the bank to which the request is addressed.
`PSU-ID`	string	The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID.
`PSU-Corporate-ID`	string	The Corporate ID of the PSU when acting on behalf of an organization, e.g. Org. nummer for SE, KVK for NL.
`PSU-IP-Address`	string(ipv4)	The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU.

Request Body

Name	Type	Description
`instructedAmount`	object	The amount and currency of the money to be transferred.
`debtorAccount`	object	The account from which the payment will be debited.
`creditorName`	string	The full name of the payment recipient.
`creditorGiro`	object	The Bankgirot or Plusgirot account to which the payment will be credited.
`creditorAgent`	string	The BIC of the payment recipient's bank.
`requestedExecutionDate`	string(date)	The date when the payment is scheduled to be executed in ISO 8601 format, e.g. 2025-10-31.
`invoiceRef`	string	A custom invoice reference.
`ocrRef`	string	A Giro OCR reference.
`debtorAccountMessage`	string	A personal message from the payer to themselves.
`creditorAccountMessage`	string	A personal message from the payer to the recipient.

curl -X POST "https://api.openbankingplatform.com/iso/payments" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0..." \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 7891fc3d-85a3-4b8d-bf70-cd3805631607" \
  -H "X-BicFi: ESSESESS" \
  -H "PSU-ID: 123456789001" \
  -H "PSU-Corporate-ID: 1234567890" \
  -H "PSU-IP-Address: 152.120.171.187" \
  -d '{
    "instructedAmount": {
      "currency": "SEK",
      "amount": "1230.50"
    },
    "debtorAccount": {
      "iban": "SE123456789000532811"
    },
    "creditorName": "John Doe",
    "creditorGiro": {
      "giroNumber": "123-4567",
      "giroType": "BANKGIRO"
    },
    "creditorAgent": "HANDSESS", 
    "requestedExecutionDate": "2025-06-10",
    "invoiceRef": "Invoice Nr 4421",
    "ocrRef": "Personal note",
    "debtorAccountMessage": "Personal note"; 
    "creditorAccountMessage": "Invoice payment"
    }'

bash

Response

{
    "transactionStatus": "RCVD",
    "paymentId": "7bb5d5a1-5c44-4b0d-a3aa-9187686b38bb",
    "_links": {
        "confirmPayment": {
            "href": "/iso/payments/confirm"
        },
        "self": {
            "href": "/iso/payments/7bb5d5a1-5c44-4b0d-a3aa-9187686b38bb"
        }
    }
}

json

After the swedish-giro payment has been created, the payment flow follows the exact same steps as the guide for initiating a domestic payment.

International TP Payments

This guide will show you how to initiate an international TP payment via ISO. For international TP payments, we first need to create an FX quote.

1. Create FX Quote

Before initiating the payment, we first need to request an FX quote. This quote defines the exchange rate, fees, and the validity period.

Endpoint

POST /psd2/paymentinitiation/v1/fx

http

Request Headers

Name	Type	Description
`X-Request-ID`	string(uuid)	The ID of the request, unique to the call, as determined by the initiating party.

Request Body

Name	Type	Description
`sourceCurrency`	string	Credentials to authenticate the client.
`targetCurrency`	string	Specifies the request format.
`requestedExecutionDate`	string(date)	The ID of the request, unique to the call, as determined by the initiating party.
`countryCode`	string	The ID of the request, unique to the call, as determined by the initiating party.
`amount`	string	The ID of the request, unique to the call, as determined by the initiating party.

curl -X POST "https://api.openbankingplatform.com/psd2/paymentinitiation/v1/fx" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0..." \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 513742f2-c73d-46f4-bbe0-7494d7162f81" \
  -d '{
    "sourceCurrency": "SEK",
    "targetCurrency": "EUR", 
    "requestedExecutionDate": "2026-01-01",
    "countryCode": "NL", 
    "amount": "130.00" 
    }'

bash

Response

{
  "fxQuoteId": "14719403-4735-435b-9f97-d3fe00809e59",
  "fxRate": "10.87410000",
  "fee": "1.50",
  "totalAmount": "110.25",
  "validFrom": "2024-08-23T14:12:57Z",
  "validTo": "2024-08-24T14:12:57Z"
}

json

The response contains an fxQuoteId which will be need to be referenced in the request headers of the payment request. Please note that the payment needs to be signed within 1 hour of creating the FX quote. If the payment does not reach a finalised state within this timeframe, the FX contract will be voided and a new fxQuoteId will need to be created.

2. Create Payment

Once we have an FX quote, we can create an international TP payment including the fxQuoteId in the request headers, and specifying the details of the transaction in the request body.

Endpoint

POST /iso/payments/international-tp

http

Request Headers

Name	Type	Description
`X-Request-ID`	string(uuid)	The ID of the request, unique to the call, as determined by the initiating party.
`X-BicFi`	string	The BIC of the bank to which the request is addressed.
`PSU-ID`	string	The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID.
`PSU-Corporate-ID`	string	The Corporate ID of the PSU when acting on behalf of an organization, e.g. Org. nummer for SE, KVK for NL.
`FX-Quote-Id`	string	The ID of the FX Quote to be used for the payment. Used for international TP payments only.
`PSU-IP-Address`	string(ipv4)	The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU.

Request Body

Name	Type	Description
`instructedAmount`	object	The amount and currency of the money to be transferred.
`debtorAccount`	object	The account from which the payment will be debited.
`creditorName`	string	The full name of the payment recipient.
`creditorAccount`	object	The account to which the payment will be credited.
`creditorAddress`	object	The address of the payment recipient.
`creditorAgent`	string	The BIC of the payment recipient's bank.
`creditorAgentName`	string	The name of the payment recipient's bank.
`requestedExecutionDate`	string(date)	The date when the payment is scheduled to be executed in ISO 8601 format, e.g. 2025-10-31.
`remittanceInformationUnstructured`	string	A free-text field for remittance information on the payment.
`debtorAccountMessage`	string	A personal message from the payer to themselves.

curl -X POST "https://api.openbankingplatform.com/iso/payments/international-tp" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0..." \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 69de0a9d-a5e0-47cd-bdf8-f33dc4028e0c" \
  -H "X-BicFi: ESSESESS" \
  -H "PSU-ID: 123456789001" \
  -H "PSU-Corporate-ID: 1234567890" \
  -H "FX-Quote-Id: 11b192ce-8326-44c3-a9e5-65ecb21628a5" \
  -H "PSU-IP-Address: 152.120.171.187" \
  -d '{
    "instructedAmount": {
      "currency": "SEK",
      "amount": "1230.50"
    },
    "debtorAccount": {
      "iban": "SE123456789000532811"
    }, 
    "creditorName": "John Doe",
    "creditorAccount": {
      "iban": "NL123456789000222333"
    },
    "creditorAddress": {
        "country": "NL"
    },
    "creditorAgent": "RABONL2U", 
    "creditorAgentName": "Coöperatieve Rabobank U.A.",
    "requestedExecutionDate": "2025-06-10",
    "remittanceInformationUnstructured": "Ref Number Merchant",
    "debtorAccountMessage": "Personal note"
    }'

bash

Response

{
    "transactionStatus": "RCVD",
    "paymentId": "00700590-5f23-4023-b89e-ac39a55174a5",
    "_links": {
        "confirmPayment": {
            "href": "/iso/payments/confirm"
        },
        "self": {
            "href": "/iso/payments/00700590-5f23-4023-b89e-ac39a55174a5"
        }
    }
}

json

After the international TP payment has been created, the payment flow follows the exact same steps as the guide for initiating a domestic payment.

Payments KYC

​Domestic Payments

​1. Create Payment

​Endpoint

​Request Headers

​Request Body

​Response

​2. Confirm Payment

​Endpoint

​Request Headers

​Request Body

​Response

​3. Authorise Payment

​4. Get Payment

​Endpoint

​Path Parameters

​Request Headers

​Response

​Swedish Giro Payments

​1. Create Payment

​Endpoint

​Request Headers

​Request Body

​Response

​International TP Payments

​1. Create FX Quote

​Endpoint

​Request Headers

​Request Body

​Response

​2. Create Payment

​Endpoint

​Request Headers

​Request Body

​Response

Domestic Payments

1. Create Payment

Endpoint

Request Headers

Request Body

Response

2. Confirm Payment

Endpoint

Request Headers

Request Body

Response

3. Authorise Payment

4. Get Payment

Endpoint

Path Parameters

Request Headers

Response

Swedish Giro Payments

1. Create Payment

Endpoint

Request Headers

Request Body

Response

International TP Payments

1. Create FX Quote

Endpoint

Request Headers

Request Body

Response

2. Create Payment

Endpoint

Request Headers

Request Body

Response