Payments
The Payment Initiation Service (PIS) allows you to initiate payments directly from the PSU's bank account through the Open Payments platform. Several different types of payments can be initiated through the PIS, each identified by a specific payment-product in the endpoint path. The general flow for initiating a payment is the same for all products except cross-border, which includes an additional first step of creating an FX quote. The guide below therefore outlines these two distinct payment creation flows.
Requests to the PIS API require an access token with
scopeset topaymentinitiationcorporate.
Standard Payment Creation
1. Create Payment
This step initiates the payment. Here, set the payment-service to payments and select the payment-product according to the type of payment you are creating.
Endpoint
Code
The below examples show how to define the payment instructions per payment-product.
Domestic
Local payments in the bank's national system.
Code
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. |
TPP-Redirect-Preferred | boolean | Indicates a preference for redirect-based SCA over decoupled when set to true. The bank may not support both types. |
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. |
Code
Response
Code
Fraudulent Account Screening
If the creditor account is listed on Svensk Handel's watchlist, the response will additionally contain a warning message:
Code
Swedish Giro
Domestic payments within Sweden via the Bankgirot and Plusgirot systems.
Code
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. |
TPP-Redirect-Preferred | boolean | Indicates a preference for redirect-based SCA over decoupled when set to true. The bank may not support both types. |
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. |
Code
Response
Code
OCR Reference Validation
If the creditor has OCR reference validation enabled, the response will additionally contain a warning message if the provided OCR reference is invalid:
Code
SEPA Credit Transfer
EUR-denominated payments within the SEPA zone.
Code
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. |
TPP-Redirect-Preferred | boolean | Indicates a preference for redirect-based SCA over decoupled when set to true. The bank may not support both types. |
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. |
Code
Response
Code
Verification of Payee (VoP)
For SEPA payments in the Eurozone, the response will additionally include a VoP result based on the provided creditor details:
Code
Cross-border Payment Creation
1. Create FX Quote
The cross-border product enables 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.
Endpoint
Code
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. |
Code
Response
Code
The response contains an fxQuoteId which you will need to reference in the request headers of the cross-border payment request.
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
This step initiates the cross-border payment. Set the payment-service to payments and the payment-product to cross-border, and include the FX-Quote-ID from the previous step in the request headers.
Cross-border
Payments to foreign countries using FX quotes.
Code
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. |
TPP-Redirect-Preferred | boolean | Indicates a preference for redirect-based SCA over decoupled when set to true. The bank may not support both types. |
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. |
Code
Response
Code
Single Payment Authorisation and Status
Once you have created a payment, it must be authorised by the PSU before it can be executed. Single payment authorisation is used when an individual payment is signed on its own through a dedicated SCA flow.
2. Authorise Payment
See the Authorisations guide for instructions on how to complete the authorisation process for a payment.
3. Get Payment Status
After completing the authorisation flow, check the status of the payment by polling the following endpoint.
Endpoint
Code
Path Parameters
| Name | Type | Description |
|---|---|---|
payment-service | string | The type of payment to initiate, e.g. payments for single payments. |
payment-product | string | The scheme and format of the payment, e.g. domestic for domestic payments. |
paymentId | string(uuid) | 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. |
TPP-Redirect-Preferred | boolean | Indicates a preference for redirect-based SCA over decoupled when set to true. The bank may not support both types. |
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. |
Include an X-Feature-Flags header set to new-statuses-global to get harmonised payment statuses across all supported banks.
Code
Response
Code
Payments can have a number of different statuses. 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.
Signing Basket Authorisation and Status
Alternatively to authorising each payment separately, signing baskets allow several initiated payments to be grouped and authorised in a single SCA flow. Once a signing basket is signed, each payment within it is signed simultaneously, ensuring consistency and reducing friction. All supported payment types can be included in a signing basket.
2. Create Signing Basket
Once you have created your payments, you can create a signing basket and include each payment's paymentId in the request body.
Endpoint
Code
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. |
TPP-Redirect-Preferred | boolean | Indicates a preference for redirect-based SCA over decoupled when set to true. The bank may not support both types. |
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 signing basket. |
Code
3. Authorise Signing Basket
See the Authorisations guide for instructions on how to complete the authorisation process for a signing basket.
4. Get Signing Basket Status
After completing the authorisation flow, check the status of the payment by polling the following endpoint.
Endpoint
Code
Path Parameters
| Name | Type | Description |
|---|---|---|
basketId | string | The ID of the signing basket 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. |
TPP-Redirect-Preferred | boolean | Indicates a preference for redirect-based SCA over decoupled when set to true. The bank may not support both types. |
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. |
Code
Response
Code
Signing baskets can have a number of different statuses. Here, you want to check if the basket was rejected, in which case transactionStatus would have the value RJCT. If not, then you are done.
Note that the basket status reflects the authorisation outcome, not the execution status of individual payments. Verify each payment's status via the Get Payment Status endpoint regardless of the signing basket's scaStatus.

