IBAN Add API

Description: Create a new IBAN account record. If iban is provided in the request, it will be validated for format and uniqueness first. If iban is omitted, one will be allocated automatically from the pre-generated IBAN pool and bound to the current api_account.

Production API URL: #/api/iban/add Sandbox API URL: https://ibantest.yabandpay.com/api/iban/add

Method: POST

Header:

Authorization: Bearer {api_account_token}
Content-Type: application/json

1. Request Format (Unified)

1.1 data Object (Business Parameters)

1.2 Signature Algorithm (HMAC-SHA256)

Client-side calculation steps (strict order):

1. Remove the sign field from the raw request body. If a role field exists, it must also be excluded.
2. Flatten every field inside data to the top level, together with uid / timestamp / nonce.
3. Sort the flattened fields by key in ascending dictionary order (ksort()).
4. Concatenate them as a query string in the form k1=v1&k2=v2&k3=v3.
5. Compute HMAC-SHA256 with the account secret_key, and lowercase the hex digest as the value of sign.

Signature formula:
sign = hash_hmac('sha256', implode('&', ksort(merge(data, {uid,timestamp,nonce})) ), secret_key)

Signature example (PHP):

$secretKey = 'your_account_secret_key';
$body = [
    'uid'       => '900001',
    'timestamp' => 1731926400,
    'nonce'     => 'Qe3CkH2xP8',
    'data'      => [
        'request_id'    => 'req_202411180049',
        'customer_id'   => 'CUST20260001',
        'timezone'      => 'Asia/Shanghai',
        'customer_type' => 'legal_entity',
        'holder_name'   => 'Yabandpay B.V.',
    ],
];
$sign = getSignByYabandPayV3($body, $secretKey);
$body['sign'] = $sign;

2. Request Example

{
    "uid": "900001",
    "timestamp": 1731926400,
    "nonce": "Qe3CkH2xP8",
    "sign": "A1AC665F9B40F7C51212BCE080F5B987",
    "data": {
        "request_id": "req_202411180049",
        "customer_id": "CUST20260001",
        "customer_type": "legal_entity",
        "holder_name": "Yabandpay B.V.",
        "alternative_name": "YB HQ",
        "creditor_identifier": "YABAND001",
        "access": 1,
        "status": 1,
        "remark": "Dutch HQ corporate account"
    }
}

3. Response Example

Success (200)

{
    "status": true,
    "code": "200",
    "data": {
        "id": 1001,
        "customer_type": "legal_entity",
        "customer_id": "CUST20260001",
        "holder_name": "Yabandpay B.V.",
        "alternative_name": "YB HQ",
        "creditor_identifier": "YABAND001",
        "bic": "YABNNL22",
        "iban": "NL08YABN0187654321",
        "currency": "EUR",
        "balance": "0.00",
        "access": 1,
        "access_label": "full",
        "status": 1,
        "status_label": "active",
        "remark": "Dutch HQ corporate account",
        "api_account_id": 1,
        "created_at": 1784851200,
        "updated_at": 1784851200,
        "request_id": "req_202411180049",
        "response_id": "TRADE20260819XXXXXX"
    },
    "message": ""
}

Common Failure Codes

Invalid parameters example:

{
    "status": false,
    "code": "-3002",
    "message": "The given data was invalid.",
    "data": {}
}

Invalid IBAN format example:

{
    "status": false,
    "code": "-3004",
    "message": "invalid NL IBAN",
    "data": {}
}

4. Special Notes

1. About the verify.api.sign middleware:

   • Validates that the header Authorization: Bearer {token} matches uid;
   • Checks the IP whitelist;
   • Re-computes the signature and compares it;
   • Once passed, flattens all business fields inside data onto the request top level and injects iban_api_user_info (account details array).

2. About automatic IBAN allocation:

   • If data.iban is not provided, the API fetches one row from the iban_generated pool in a concurrency-safe manner (FOR UPDATE SKIP LOCKED + transaction + conditional UPDATE to ensure different accounts never share the same IBAN);
   • Once allocated, both iban.api_account_id and iban_generated.api_account_id are immediately set to the current API account;
   • The pool lock TTL defaults to 1800 seconds (30 minutes). Stale locks are released by a scheduled job.

3. About NL IBAN format validation (when explicitly provided):

   • The rule is: must start with NL, and the overall Mod97-10 remainder must be 1;
   • Current default pattern requires YABN followed by 01 + 8 digits (the account part totals 10 digits).

4. Callers can use request_id for idempotency: we echo it in responses for bilateral correlation.