Overview

---

Error Codes

Code	Description
1001	More than 500 payment instructions uploaded in a single request.
9403	ISO 20022 document validation error (does not conform to XSD schema).
9999	Internal server error related to document processing.

---

ISO 20022 Validation Error Codes:

Error Code	Description
BE04	MsgId is missing or exceeds 35 characters. Must be non-empty and unique.
BE04	CreDtTm is missing or has an invalid format. Expected format: YYYY-MM-DDThh:mm:ssZ.
AM04	NbOfTxs is missing, non-integer, or ≤ 0. Must be a positive integer.
AM04	CtrlSum is missing, < 0, or has more than 2 decimal places.
BE04	InitgPty/Nm is missing or contains invalid characters.
BE04	PmtInfId is missing or exceeds 35 characters.
RC01	PmtMtd value is missing or not equal to “TRF”.
AM04	NbOfTxs is missing, non-integer, or ≤ 0.
AM04	CtrlSum < 0 or has more than 2 decimal places.
BE04	InstrPrty is missing or not valid.
BE04	Invalid date format. Required ISO format: YYYY-MM-DD.
BE04	Dbtr/Nm is missing or contains invalid characters.
AC01	Invalid IBAN: length or format does not match the country standard (e.g., KZ...).
BE04	EndToEndId is missing, not unique, or exceeds 35 characters.
AM04	InstdAmt is missing, ≤ 0, or has more than 2 decimal places.
RC01	BIC is missing or does not match the format (A–Z/0–9 only, length 8 or 11).
BE04	Cdtr/Nm is missing or contains invalid characters.
AC01	Recipient IBAN is invalid — length or checksum does not match format.
BE04	Payment purpose is missing or contains invalid characters.
BE04	KBE code is missing or does not match the directory.
BE04	IIN/BIN is missing or not 12 digits long.

---

Statuses

Possible ISO 20022 settlement section statuses:

ISO Code	Internal Status	Description
ACSC	success	Successfully sent to the bank
ACSP	process	In queue for processing
RJCT	error	Sending error, possibly rejected by the bank
PDNG	downloaded	Uploaded but not yet processed

---

Restrictions

• The maximum number of payment instructions in one ISO document is 500.
• An unsupported document_type will result in a processing error.
• An unsupported document_body will result in a processing error.

---

Request authorization

• A JWS token generated using HS256 is used for authorization.

• The token is transmitted in the request header: X-JWS-Signature: <generated_jws_token>

• Signature algorithm: HS256 (HMAC SHA256)

• Secret key: secret_key (Partner API key, issued by the manager)

• Auth_id: represents the User ID of the merchant/partner in the system

Example of a JWS signature:

const crypto = require('crypto');

function base64url(v) {
    return v.replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");
}

function makeSignature({ rawBody, urlPath, method, secret, auth_id }) {
    const uri = "/" + urlPath.join(',');
    const header = {
        alg: "HS256",
        auth_id: auth_id,
        uri: uri,
        method: method,
        params: ""
    };

    const headerStr = JSON.stringify(header);
    const encodedHeader = base64url(Buffer.from(headerStr, 'utf8').toString('base64'));
    const encodedPayload = base64url(Buffer.from(rawBody, 'utf8').toString('base64'));
    const toSign = encodedHeader + "." + encodedPayload;
    const signature = crypto
        .createHmac("sha256", secret)
        .update(toSign)
        .digest("base64");

    return encodedHeader + ".." + base64url(signature);
};

Example usage

const requestObj = {
    "document_type": "iso20022",
    "document_body": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>..."
};

// Body должен быть строкой, не JSON-объектом
const rawBody = JSON.stringify(requestObj);

const token = makeSignature({
    rawBody: rawBody,
    urlPath: ['api', 'v5', 'partner', 'settlement-partitions'],
    method: "POST",
    secret: "your_partner_api_secret_key",
    auth_id: "user_id"
});

console.log("Generated JWS Token:", token);