neotek Empowering Financial Innovation

BulkPayment

POSThttps://test.api.neotek.sa/b2b-unified/v1/payments/bulk

Sandbox URL · in Production call https://api.neotek.sa

Sends a batch of payments in one call. Every item runs against the same bank, so bankCode sits at batch level rather than on each payment.

Body:

Parameter	Required	Description
`bankCode`	Required	which bank executes the batch, by BIC: `RJHISARI` or `ARNBSARI`
`payments`	Required	the payment items, as an array

Each item takes the same fields as a single payment apart from bankCode.

The payment:

Parameter	Required	Description
`transactionReference`	Required	your own reference, up to 16 characters
`paymentDate`	Required	the date the payment is made
`currency`	Required	for example `SAR`
`amount`	Required	the amount as a string, for example `5000.00`
`purposeCode`	Required	why the payment is being made
`transactionDescription`	Optional	up to 35 characters
`chargeOption`	Optional	who bears the charges: `SHA` (the default), `OUR` or `BEN`

Who pays:

Parameter	Required	Description
`debtorName`	Required	up to 35 characters
`debtorAccountIban`	Required	the account the money leaves
`debtorAddressLine1`, `debtorAddressLine2`, `debtorAddressLine3`	Required	up to 35 characters each

Who is paid:

Parameter	Required	Description
`beneficiaryName`	Required	up to 35 characters
`beneficiaryAccountIban`	Required	the account the money arrives in
`beneficiaryBankBic`	Required	the receiving bank's BIC, 8 or 11 characters
`beneficiaryAddressLine1`, `beneficiaryAddressLine2`, `beneficiaryAddressLine3`	Required	up to 35 characters each

Headers:

Parameter	Required	Description
`authorization`	Required	`Bearer <ACCESS_TOKEN>`
`content-type`	Required	`application/json`

cURL

curl -X POST 'https://test.api.neotek.sa/b2b-unified/v1/payments/bulk' \  --header 'authorization: Bearer <ACCESS_TOKEN>' \  --header 'content-type: application/json' \  --data '{    "bankCode": "ARNBSARI",    "payments": [      {        "transactionReference": "BULK6701A",        "paymentDate": "2026-02-11",        "currency": "SAR",        "amount": "5000.00",        "debtorName": "Neotek Trading Co",        "debtorAccountIban": "SA1030000012345678901004",        "debtorAddressLine1": "Building 123, King Fahd Road",        "debtorAddressLine2": "Al Olaya District",        "debtorAddressLine3": "Riyadh, Saudi Arabia",        "beneficiaryName": "Mohammed Ali",        "beneficiaryAccountIban": "SA1080000012345678901003",        "beneficiaryBankBic": "RJHISARI",        "beneficiaryAddressLine1": "Apartment 101",        "beneficiaryAddressLine2": "Al Rawdah District",        "beneficiaryAddressLine3": "Jeddah, Saudi Arabia",        "purposeCode": "Payroll and Benefits",        "transactionDescription": "January 2026 Salary"      }    ]  }'

Response — the batch is identified by batchReference, not a per-payment id, and cannot be enquired about for 30 minutes

JSON

{  "success": true,  "code": "PAYMENT_ACCEPTED",  "message": "Batch accepted for processing",  "batchReference": "BATCH-20260211-001",  "statusMessage": "Your payment is being processed and can be enquired after 30 minutes"}

Errors — each failure carries an error category and a specific code

Status	Codes	Typical cause
`400` `ERROR_CATEGORY_VALIDATION_FAILED`	`INVALID_IBAN`, `INVALID_AMOUNT`, `INVALID_ACCOUNT`, `INVALID_CURRENCY`, `INVALID_BANK_CODE`, `INVALID_REFERENCE`, `ACCOUNT_NOT_FOUND`, `BENEFICIARY_NOT_FOUND`	Bad or missing field — wrong IBAN format, unknown `bankCode`, reference over 16 characters
`401` `ERROR_CATEGORY_AUTH_FAILED`	`AUTH_FAILED`, `CREDENTIALS_NOT_FOUND`, `UNAUTHORIZED`	Token missing or expired, or no vault credentials for your app with that bank
`404` `ERROR_CATEGORY_NOT_FOUND`	`NOT_FOUND`	Resource not found
`409` `ERROR_CATEGORY_DUPLICATE`	`DUPLICATE_TRANSACTION`, `DUPLICATE_REFERENCE`, `DUPLICATE_PAYMENT`	You reused a `transactionReference`
`422` `ERROR_CATEGORY_BANK_REJECTED`	`INSUFFICIENT_FUNDS`, `AMOUNT_LIMIT_EXCEEDED`, `DAILY_LIMIT_EXCEEDED`, `INVALID_PAYMENT_DATE`, `ACCOUNT_BLOCKED`, `ACCOUNT_CLOSED`, `PAYMENT_NOT_ALLOWED`	The request was valid; the bank declined it
`500` `ERROR_CATEGORY_SYSTEM_FAILURE`	`SYSTEM_ERROR`, `INTERNAL_ERROR`	Gateway-side failure
`503` `ERROR_CATEGORY_TEMPORARY_FAILURE`	`SERVICE_UNAVAILABLE`, `BANK_UNAVAILABLE`, `NETWORK_ERROR`, `NETWORK_TIMEOUT`, `CONNECTION_REFUSED`, `REQUEST_TIMEOUT`	Transient — retry with backoff

PreviousSinglePaymentStatus NextBulkPaymentStatus