Create beneficiary | CrissCross

curl -X POST https://api.crisscross.money/v1/beneficiaries \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "string",
  "entityType": "business",
  "address": {},
  "currency": "NGN",
  "accountDetails": [
    {
      "type": "account_number",
      "value": "string"
    }
  ],
  "routingDetails": [
    {
      "rail": "fiat",
      "paymentType": "ach",
      "routingNumber": "021000021",
      "routingNumberType": "aba",
      "bank": {
        "name": "JPMorgan Chase Bank",
        "address": "270 Park Avenue, New York, NY 10017"
      }
    }
  ]
}'

{
  "beneficiaryId": "ben_f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "pending",
  "currency": "NGN",
  "name": "Acme Supplier Ltd",
  "entityType": "business",
  "accountDetails": [
    {
      "type": "account_number",
      "value": "1234567890"
    }
  ],
  "routingDetails": [
    {
      "rail": "fiat",
      "paymentType": "local",
      "routingNumber": "044",
      "routingNumberType": "other",
      "bank": {
        "name": "Access Bank",
        "address": "14/15 Prince Alaba Oniru Rd, Lagos"
      }
    }
  ],
  "createdAt": "2026-04-21T14:14:55Z",
  "address": {
    "line1": "100 Market Street",
    "city": "Lagos",
    "postcode": "100001",
    "country": "NG"
  },
  "activatedAt": null
}

Beneficiary created with status: pending. Transitions to active after async compliance validation. Poll until active before use.

Idempotency: Idempotency-Key header recommended (UUIDv4, persisted before the request, reused on retries). Omitting it is permitted — the caller accepts all retry and duplicate risk.

Beneficiary created with `status: pending`. Transitions to `active` after async compliance validation. Poll until `active` before use. Idempotency: **`Idempotency-Key` header recommended** (UUIDv4, persisted before the request, reused on retries). Omitting it is permitted — the caller accepts all retry and duplicate risk.

Authentication

AuthorizationBearer

Token obtained via the login flow.

Request

This endpoint expects an object.

namestringRequired<=140 characters

Legal name. ≤ 140 chars.

entityTypeenumRequired

addressobjectRequired

currencystringRequired

ISO 4217.

accountDetailslist of objectsRequired

routingDetailslist of objectsRequired

Response

Beneficiary created with status: pending. Transitions to active after async compliance validation. Poll until active before use.

beneficiaryIdstring

statusenum

Poll until active before referencing in a withdrawal.

currencystring

One currency per beneficiary.

namestring

Legal name.

entityTypeenum

accountDetailslist of objects

routingDetailslist of objects

createdAtdatetime

statusReasonenum or null

addressobject

activatedAtdatetime or null

Errors

400

Bad Request Error

401

Unauthorized Error

Authentication

Headers

Request

Response

Errors