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

Allowed values:

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.

Allowed values:

currencystring

One currency per beneficiary.

namestring

Legal name.

entityTypeenum

Allowed values:

accountDetailslist of objects

routingDetailslist of objects

createdAtdatetime

statusReasonenum or null

Allowed values:

addressobject

activatedAtdatetime or null

Errors

400

Bad Request Error

401

Unauthorized Error

Authentication

Headers

Request

Response

Errors