API Reference

/ics/v3/payments/batch-transfer

post
https://sandbox.neonomics.io/ics/v3/payments/batch-transfer

Initiates a batch payment with multiple creditors. Each payment in the batch shares the same debtor account.
This endpoint supports both domestic and scheduled domestic payments:

  • For domestic payments: omit the requestedExecutionDate field in creditor entries
  • For scheduled domestic payments: include the requestedExecutionDate field in creditor entries

The debtorAccount can be either 'iban', 'bban', or 'sortCodeAccountNumber'.
The creditorAccount in each creditor entry can be either 'iban', 'bban', 'sortCodeAccountNumber' (UK), 'BGNR', or 'PGNR'.

Each creditor can optionally include a referenceId - a user-generated reference ID to keep track of payments
for pairing payment IDs with reference IDs once they receive the response from this API.

To enable a custom redirect, include the x-redirect-url parameter in the request header. The callback will then include a resource_id (the batch-id) and a result
(the request's status, either 'OK' or 'FAILED'). This API will return a 1426 error if consent is required and a 1428 'payment authorization required' if the payment requires SCA.
If you get error code '1428' then you have to call API '/ics/v3/payments/batch-transfer/{batchId}/authorize' to get authorization URL. Once you receive the URL, you can use it to get
authorized with the respective bank. This single authorization will cover all payments in the batch.

NOTE: The max limit for creditors in a batch payment is 20.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
debtorAccount
object
required

Debtor account info, which consists of the account scheme (account type) and the account identifier (account number).
The account scheme can be either 'iban', 'bban', or 'sortCodeAccountNumber' (UK).

string
required

Debtor's name (the payer).

string
enum
required

3 letter currency code for the account following ISO 4217.

Allowed:
string

Unique reference/id assigned by the initiating party to identify the transaction for their own usage.
This identification is passed on, unchanged, throughout the whole payment flow.
Max character length is 35 as defined by iso 20022.

creditors
array of objects
required
length between 1 and 20

Array containing details of each recipient in the batch payment.

creditors*

Individual creditor details within a batch payment. Each creditor can be either domestic
or domestic scheduled based on the presence of the requestedExecutionDate field.

string
required

Creditor's name (the payee).

string

Optional user-generated reference ID to keep track of payments. This allows pairing payment IDs
with reference IDs once the response is received from the API.

creditorAccount
object
required

Creditor account info, which consists of the account scheme (account type) and the account identifier (account number).
The account scheme can be either 'iban', 'bban', 'sortCodeAccountNumber' (UK), 'BGNR', or 'PGNR'.

string
required

Monetary amount to be transferred. Currency precision ranges from zero to two decimal places,
separated by a dot as defined in the ISO 4217 and ISO 20022 standards.

string

Remittance information about the payment, such as notes about the transaction.
The maximum character limit is 140 (exceptions vary by bank and country).
Note that either remittanceInformationUnstructured or remittanceInformationStructured must be included for each creditor entry.

remittanceInformationStructured
object

Unique identification for the payment, issued by the creditor in accordance with a national standard (e.g., 'KID' in Norway, 'OCR' in Sweden).
Note that either remittanceInformationUnstructured or remittanceInformationStructured must be included for each creditor entry.

string

Optional field. The date that the payment is requested to be executed. It must be a future date following the ISO 8601 format (yyyy-mm-dd).
If this field is provided, the payment will be processed as a scheduled payment.

paymentMetadata
object
Headers
string
required

The session Id returned in the response body when this session was created.

string
required

String that uniquely identifies a single end-user or device.

string

URL where the end-user gets redirected after a consent or payment authorization.
The URL must be registered in the Developer Portal under the relevant application.

string
required

The IP Address of the end-user (PSU), which must be provided if the PSU actively requests information.
If this value is not provided, then the call will count towards the number of TPP calls without PSU interaction.
Leave it empty if the end user is not actively requesting account information, such as during automatic background updates.
Provided in either IPv4 or IPv6 format.

string

Identifier of the end-user, passed as the base64-encoded value of an encrypted string following
the guidelines given in Documentation > Development > Sensitive end-user data.
This parameter is required if the value of 'personalIdentificationRequired' returned from the /banks endpoint is "true".

string

Corporate identifier of the end-user's organisation, used for business/corporate consents (the business-accounts scope).

Currently effective for Länsförsäkringar and Sparebanken Vest (Folio, bank folio.noSPAVNOBB).

  • Länsförsäkringar: required in addition to x-psu-id, and both are distinct. x-psu-id carries the
    signing person's personnummer (SSN), type SSSN; x-psu-corporate-id carries the organisationsnummer
    (org number), type SON. Confirmed with the bank: both values must be exactly 12 numeric digits — a
    continuous digit string with no hyphens, spaces, letters, or special characters (e.g. 12345678-0987 is
    not valid). Fewer or more than 12 digits fails validation.
  • Sparebanken Vest / Folio: required on both consent initiation and every subsequent account/transaction
    read, not only at consent time. Carries the 9-digit Norwegian organisation number. x-psu-id is optional
    here and, if sent, must be the authorising person's national identifier — never the organisation number.

For all other banks this header is currently ignored, even those whose corporate flows rely on a corporate
identifier (e.g. DNB) — those flows continue to work via x-psu-id as today. Do not rely on this header for any
bank other than the ones listed above; support for additional banks may be added later.

Ignored for personal-scope consents.

string

The host where the request is originating from.
If you are using end to end encryption from our developer portal then this header is mandatory.

string

The request originating date.
If you are using end to end encryption from our developer portal then this header is mandatory.

string

The signature header consisting of the signature string
If you are using end to end encryption from our developer portal then this header is mandatory.

string

A Base64-encoded hash of the request body If you are using end to end encryption from our developer portal then this header is mandatory for all post/put/patch requests.

Responses

Updated 11 months ago

Did this page help you?
Language
Credentials
Bearer
JWT
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 11 months ago

Did this page help you?