# ISO Payments

The ISO Payments API allows you 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 authorisation. 

> Requests to the ISO Payments API require an [access token](get_access_token.md) with `scope` set to `paymentinitiation` `corporate`. 

## Standard Payment Creation

### 1. Create Payment 

The first step is to create the payment you wish to upload in file format.

#### Endpoint

```http
POST /iso/payments
```

### Domestic

Local account-to-account transfers in the bank's national system.

#### 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 organisation, e.g. Org. nummer for SE, KVK for NL.        |
| `PSU-IP-Address`   | string(ipv4) | The IP address of the PSU from the HTTP request between the PSU and the TPP.                                      |    
| `PSU-User-Agent`   | string       | The Agent header from the HTTP request between the PSU and the TPP, identifying the browser used 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.                                        |
| `creditorAccount`                   | object       | The account to which the payment will be credited.                                         |
| `creditorName`                      | string       | The full name of the payment recipient.                                                    |
| `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.                               |

```bash
curl -X POST "https://api.openbankingplatform.com/iso/payments" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 2e02a131-a35a-450f-a736-9a06086f3337" \
  -H "X-BicFi: ESSESESS" \
  -H "PSU-ID: 199002092386" \
  -H "PSU-Corporate-ID: 5560160680" \
  -H "PSU-IP-Address: 152.120.171.187" \
  -H "PSU-User-Agent: mozilla/5.0" \
  -d '{
        "instructedAmount": {
          "amount": "1230.50",
          "currency": "SEK"
        },
        "debtorAccount": {
          "iban": "SE4550000000058398257466",
          "currency": "SEK"
        },
        "creditorAccount": {
          "iban": "SE1412000000000012345678",
          "currency": "SEK"
        },
        "creditorName": "Acme AB",
        "requestedExecutionDate": "2025-06-10",
        "remittanceInformationUnstructured": "Ref Number Merchant"
      }'
```

### Swedish Giro

Domestic payments within Sweden via the Bankgirot and Plusgirot systems.

#### 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 organisation, e.g. Org. nummer for SE, KVK for NL.        |
| `PSU-IP-Address`   | string(ipv4) | The IP address of the PSU from the HTTP request between the PSU and the TPP.                                      |
| `PSU-User-Agent`   | string       | The Agent header from the HTTP request between the PSU and the TPP, identifying the browser used 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.                                        |
| `creditorGiro`           | object       | The Bankgirot or Plusgirot account to which the payment will be credited.                  |
| `creditorName`           | string       | The full name of the payment recipient.                                                    |
| `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.                                                                      |

```bash
curl -X POST "https://api.openbankingplatform.com/iso/payments" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 7891fc3d-85a3-4b8d-bf70-cd3805631607" \
  -H "X-BicFi: ESSESESS" \
  -H "PSU-ID: 199002092386" \
  -H "PSU-Corporate-ID: 5560160680" \
  -H "PSU-IP-Address: 152.120.171.187" \
  -H "PSU-User-Agent: mozilla/5.0 \
  -d '{
        "instructedAmount": {
          "amount": "1230.50",
          "currency": "SEK"
        },
        "debtorAccount": {
          "iban": "SE4550000000058398257466",
          "currency": "SEK"
        },
        "creditorGiro": {
          "giroNumber": "1234-5678",
          "giroType": "BANKGIRO"
        },
        "creditorName": "Acme AB",
        "requestedExecutionDate": "2025-06-10",
        "ocrRef": "1234567890"
      }'
```

### SEPA Credit Transfers

EUR-denominated payments within the SEPA zone.

#### 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 organisation, e.g. Org. nummer for SE, KVK for NL.        |
| `PSU-IP-Address`   | string(ipv4) | The IP address of the PSU from the HTTP request between the PSU and the TPP.                                      |
| `PSU-User-Agent`   | string       | The Agent header from the HTTP request between the PSU and the TPP, identifying the browser used 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.                                        |
| `creditorAccount`                   | object       | The account to which the payment will be credited.                                         |
| `creditorName`                      | string       | The full name 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.                               |   

```bash
curl -X POST "https://api.openbankingplatform.com/iso/payments" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: a062542e-8669-43e0-b67d-593d03af0e0f" \
  -H "X-BicFi: ESSESESS" \
  -H "PSU-ID: 199002092386" \
  -H "PSU-Corporate-ID: 5560160680" \
  -H "PSU-IP-Address: 152.120.171.187" \
  -H "PSU-User-Agent: mozilla/5.0" \
  -d '{
        "instructedAmount": {
          "amount": "130.00",
          "currency": "EUR"
        },
        "debtorAccount": {
          "iban": "SE123456789000532811",
          "currency": "EUR"
        },
        "creditorAccount": {
          "iban": "FI2112345600000785",
          "currency": "EUR"
        },
        "creditorName": "Acme AB",
        "creditorAgent": "NDEAFIHH", 
        "creditorAgentName": "Nordea Bank Abp", 
        "requestedExecutionDate": "2025-05-19",
        "remittanceInformationUnstructured": "Ref Number Merchant"
      }'
```

#### Response

```json
{
  "transactionStatus": "RCVD",
  "paymentId": "0f4f5fa1-c36f-4406-8bd6-89ea9176e6b2",
  "_links": {
    "confirmPayment": {
      "href": "/iso/payments/confirm"
    },
    "self": {
      "href": "/iso/payments/0f4f5fa1-c36f-4406-8bd6-89ea9176e6b2"
    }
  }
}
```

## Cross-border Payment Creation

Cross-border payments enable you to initiate payments to 180+ countries with built-in, real-time currency conversion — supporting both spot and forward exchange rates (up to 30 days). The first step for a cross-border payment is to create an FX quote, defining the exchange rate, fees, and the validity period.

### 1. Create FX Quote

#### Endpoint 

```http
POST /psd2/paymentinitiation/v1/fx
```

#### 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 organisation, e.g. Org. nummer for SE, KVK for NL.        |
| `PSU-IP-Address`   | string(ipv4) | The IP address of the PSU from the HTTP request between the PSU and the TPP.                                      |
| `PSU-User-Agent`   | string       | The Agent header from the HTTP request between the PSU and the TPP, identifying the browser used by the PSU.      |

#### Request Body 

| Name                     | Type         | Description                                                                                |
| ------------------------ | ------------ | ------------------------------------------------------------------------------------------ |
| `sourceCurrency`         | string       | The source currency.                                                                       |
| `targetCurrency`         | string       | The target currency.                                                                       |
| `requestedExecutionDate` | string(date) | The date when the payment is scheduled to be executed in ISO 8601 format, e.g. 2025-10-31. |
| `countryCode`            | string       | The target country.                                                                        |
| `amount`                 | string       | The requested amount in target currency.                                                   |

```bash
curl -X POST "https://api.openbankingplatform.com/psd2/paymentinitiation/v1/fx" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 98afac01-e0bb-4aa2-95fd-0b3204f8a183" \
  -H "X-BicFi: ESSESESS" \
  -H "PSU-ID: 199002092386" \
  -H "PSU-Corporate-ID: 5560160680" \
  -H "PSU-IP-Address: 152.120.171.187" \
  -H "PSU-User-Agent: mozilla/5.0" \
  -d '{
        "sourceCurrency": "SEK",
        "targetCurrency": "EUR", 
        "requestedExecutionDate": "2025-11-10",
        "countryCode": "FI", 
        "amount": "130.00" 
      }'
```

#### Response 

```json
{
  "fxQuoteId": "F100000PFM",
  "fxRate": "11.05254986",
  "fee": "1.50",
  "totalAmount": "1440.53",
  "validFrom": "2025-11-09T09:36:24.0142906Z",
  "validTo": "2025-11-10T23:59:59.0000000Z"
}
```

The response contains an `fxQuoteId` which you will need to reference in the request headers of the cross-border payment request. 

:::warning

The payment needs to be signed within **one 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 quote will need to be created. 

:::

### 2. Create Payment

In this step, you initiate the cross-border payment, including the `FX-Quote-ID` from the previous step in the request headers.

### Cross-border

Payments to foreign countries using FX quotes.

#### Endpoint

```http
POST /iso/payments/cross-border
```

#### 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 organisation, e.g. Org. nummer for SE, KVK for NL.        |
| `PSU-IP-Address`   | string(ipv4) | The IP address of the PSU from the HTTP request between the PSU and the TPP.                                      |
| `PSU-User-Agent`   | string       | The Agent header from the HTTP request between the PSU and the TPP, identifying the browser used by the PSU.      |
| `FX-Quote-ID`      | string       | The ID of the FX quote to be used for the cross-border payment.                                                   |        

#### 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.                                        |
| `creditorAccount`                   | object       | The account to which the payment will be credited.                                         |
| `creditorName`                      | string       | The full name of the payment recipient.                                                    |
| `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.                               |

```bash
curl -X POST "https://api.openbankingplatform.com/iso/payments/cross-border" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 69de0a9d-a5e0-47cd-bdf8-f33dc4028e0c" \
  -H "X-BicFi: ESSESESS" \
  -H "PSU-ID: 199002092386" \
  -H "PSU-Corporate-ID: 5560160680" \
  -H "PSU-IP-Address: 152.120.171.187" \
  -H "PSU-User-Agent: mozilla/5.0" \
  -H "FX-Quote-ID: F100000PFM" \
  -d '{
        "instructedAmount": {
          "currency": "EUR",
          "amount": "130.00"
        },
        "debtorAccount": {
          "iban": "SE4550000000058398257466",
          "currency": "SEK"
        },
        "creditorAccount": {
          "iban": "FI2112345600000785",
          "currency": "EUR"
        },
        "creditorName": "Acme AB",
        "creditorAddress": {
          "street": "Example Street",
          "buildingNumber": "5",
          "city": "Helsinki",
          "postalCode": "00160",
          "country": "FI"
        },
        "creditorAgent": "NDEAFIHH", 
        "creditorAgentName": "Nordea Bank Abp",
        "requestedExecutionDate": "2025-06-10",
        "remittanceInformationUnstructured": "Ref Number Merchant"
      }'
```

#### Response

```json
{
  "transactionStatus": "RCVD",
  "paymentId": "8fdc7945-9cc8-4f78-a905-209cc99c4607",
  "_links": {
    "confirmPayment": {
      "href": "/iso/payments/confirm"
    },
    "self": {
      "href": "/iso/payments/8fdc7945-9cc8-4f78-a905-209cc99c4607"
    }
  }
}
```

## Payment Authorisation and Status

### 2. Confirm Payment

Once you have created the ISO payment(s), confirm it to generate and upload a pain.001 file to the PSU's online bank. Multiple existing payments can be included in the file by specifying them in the `paymentIds` body parameter.

#### Endpoint 

```http
PUT /iso/payments/confirm
```

#### 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 organisation, e.g. Org. nummer for SE, KVK for NL.        |
| `PSU-IP-Address`   | string(ipv4) | The IP address of the PSU from the HTTP request between the PSU and the TPP.                                      |
| `PSU-User-Agent`   | string       | The Agent header from the HTTP request between the PSU and the TPP, identifying the browser used 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`. |

:::settings{title="Salary payments"}

To generate a salary payment file, include a `purposeCode` field with the value `SALA` in the request body. The `requestedExecutionDate` should then be the date on which the creditor will receive the funds.

:::

```bash
curl -X PUT "https://api.openbankingplatform.com/iso/payments/confirm" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: e26e0f4b-7fbd-4a23-8939-aa7e5275825c" \
  -H "X-BicFi: ESSESESS" \
  -H "PSU-ID: 199002092386" \
  -H "PSU-Corporate-ID: 5560160680" \
  -H "PSU-IP-Address: 152.120.171.187" \
  -H "PSU-User-Agent: mozilla/5.0" \
  -d '{
        "paymentIds": [
          "a3cf0daa-6d43-4156-afd4-1d859ad448a8",
          "186901d2-2022-412f-a321-60062ef1ba1c",
          "84b1133c-9ef8-41dd-8dc1-0b64a8d955d3"
        ],
        "batchBookingPreferred": "false"
      }'
```

#### Response

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

### 3. Authorise Payment

After successfully confirming the payments, the PSU then needs to log into their online bank and authorise the file. 

### 4. Get Payment

Lastly, make the following request to check the status of the payment(s) included in the file.

#### Endpoint

```http
GET /iso/payments/{paymentId}
```

#### 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 organisation, e.g. Org. nummer for SE, KVK for NL.        |
| `PSU-IP-Address`   | string(ipv4) | The IP address of the PSU from the HTTP request between the PSU and the TPP.                                      |
| `PSU-User-Agent`   | string       | The Agent header from the HTTP request between the PSU and the TPP, identifying the browser used by the PSU.      |   

:::sparkles

Include an [`X-Feature-Flags`](api.md#X-Feature-Flags) header set to `new-statuses-global` to get harmonised payment statuses across all supported banks.

:::

```bash
curl -X GET "https://api.openbankingplatform.com/iso/payments/a3cf0daa-6d43-4156-afd4-1d859ad448a8" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: c2ef85d1-dfc8-450d-b820-c90edc0f7de2" \
  -H "X-BicFi: ESSESESS" \
  -H "PSU-ID: 199002092386" \
  -H "PSU-Corporate-ID: 5560160680" \
  -H "PSU-IP-Address: 152.120.171.187" \
  -H "PSU-User-Agent: mozilla/5.0"
```

#### Response

```json 
{
  "transactionStatus": "ACSC",
  "instructedAmount": {
    "amount": "1230.50",
    "currency": "SEK"
  },
  "debtorAccount": {
    "iban": "SE4550000000058398257466",
    "currency": "SEK"
  },
  "creditorAccount": {
    "iban": "SE1412000000000012345678",
    "currency": "SEK"
  },
  "creditorName": "Acme AB",
  "requestedExecutionDate": "2025-06-10",
  "remittanceInformationUnstructured": "Ref Number Merchant"
}
```

Payments can have a number of different [statuses](enums.md#transactionstatus-1). Here, you want to check if the payment was rejected, in which case `transactionStatus` would have the value `RJCT`. If not, then you are done.