Partner API

Send N transfers under one confirmation

A loop over POST /v1/transfers behind a single confirmation code (spec §2.3). Each item is validated exactly as a single transfer would be; a failed item is reported with its refusal reason and the rest proceed. Nothing reaches the bank until the one code is verified via POST /v1/confirmations/:id, unless OnLink has enabled confirmation waiving for your account and, in production, the API key has an IP allowlist, in which case the batch is returned already confirmed and is executed immediately.

post/v1/transfers/batch

Request

Base URL
https://sandbox.onlink.africa
Auth
API key in header X-OnLink-Key

Request body

idempotencyKeystring required

A key unique to your account, for the WHOLE batch. A retried create with the same key returns the original batch rather than submitting it twice. Each item ALSO carries its own idempotencyKey — that is what dedupes the individual payments.

Example request

{
  "idempotencyKey": "batch-2026-09-16-000001",
  "items": [
    {
      "rail": "mpesa",
      "destination": {
        "accountNumber": "254700000000",
        "accountName": "Jane Wanjiku",
        "bankCode": "11",
        "bankName": "Equity Bank",
        "branchCode": "001",
        "swift": {
          "bic": "BARCKENXXXX",
          "bankCity": "Nairobi",
          "bankCountry": "Kenya",
          "chargeType": "OUR",
          "accountCurrency": "KES"
        }
      },
      "amount": {
        "currency": "KES",
        "value": "1500.00"
      },
      "partnerReference": "ACME-TRF-000123",
      "idempotencyKey": "trf-2026-09-11-000123",
      "paymentPurposeId": "SALA",
      "senderAddress": "1 Kenyatta Ave, Nairobi",
      "remark": "September rent"
    }
  ]
}

Response

The batch was created. Normally a confirmation code is sent and the response carries a confirmation object. When OnLink has enabled confirmation waiving for your account and, in production, the API key has an IP allowlist, the batch is created already confirmed, executes immediately, and the response carries no confirmation object.

idstring required

The batch id.

The batch status.

itemCountnumber required

Total items submitted, valid or not.

acceptedCountnumber required

Items that reached a successful terminal state.

failedCountnumber required

Items refused at submit or failed by the executor.

createdAtstring date-time required

ISO-8601 instant the batch was created.

confirmedAtstring date-time

ISO-8601 instant the batch was confirmed: when its confirmation code was verified, or, when confirmation is waived for your account, when the batch was created already confirmed.

Example response

{
  "id": "be9f1e6a-0000-4000-8000-000000000040",
  "status": "awaiting_confirmation",
  "items": [
    {
      "transferId": "bd9f1e6a-0000-4000-8000-000000000010",
      "idempotencyKey": "trf-2026-09-16-000123",
      "accepted": true,
      "failureCode": "TRANSFER_NAME_MISMATCH"
    }
  ],
  "createdAt": "2026-09-16T00:00:00.000Z",
  "confirmedAt": "2026-09-16T00:02:00.000Z",
  "confirmation": {
    "id": "df9f1e6a-0000-4000-8000-000000000030",
    "channel": "email",
    "deliveredTo": "o***@partner.co.ke",
    "expiresAt": "2026-09-11T00:15:00.000Z",
    "resendAvailableAt": "2026-09-11T00:00:15.000Z",
    "webhookDelivery": {
      "status": "delivered",
      "attempts": 1,
      "lastAttemptAt": "2026-09-11T00:00:02.000Z"
    },
    "waiverNotApplied": "key_without_ip_allowlist"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.