Create Payout Beneficiary

Registers a new payout beneficiary. The beneficiary is created with status: pending_review and two independent checks run asynchronously:

Account verification of the destination against the receiving network (e.g. carrier API for mobile money, bank-verification provider for bank accounts). For corridors with internal format rules (e.g. Nigerian NUBAN check-digit) the check-digit pass runs first.
AML pre-screening of the beneficiary against sanctions lists, PEP lists, and internal risk lists.

Both checks must pass for the beneficiary to transition to approved. Either check can independently block: a confirmed AML hit or a verification failure moves the beneficiary to rejected with a check-specific reason. A name mismatch returned by the network (PARTIAL_MATCH) holds the beneficiary in pending_review waiting for the merchant to accept / reject via the signal endpoint. A possible AML hit also holds the beneficiary in pending_review, but is reviewed by CrissCross’s compliance team in our screening provider’s tooling — not by the merchant.

Beneficiaries are immutable after creation — to change any detail, create a new beneficiary.

If a beneficiary with identical details already exists for the caller, the request is soft-blocked with 409 and the existing payoutBeneficiaryId is returned in the response body. Pass allowDuplicate: true to override and create a new record.

Registers a new payout beneficiary. The beneficiary is created with `status: pending_review` and two independent checks run asynchronously: - **Account verification** of the destination against the receiving network (e.g. carrier API for mobile money, bank-verification provider for bank accounts). For corridors with internal format rules (e.g. Nigerian NUBAN check-digit) the check-digit pass runs first. - **AML pre-screening** of the beneficiary against sanctions lists, PEP lists, and internal risk lists. Both checks must pass for the beneficiary to transition to `approved`. Either check can independently block: a confirmed AML hit or a verification failure moves the beneficiary to `rejected` with a check-specific reason. A name mismatch returned by the network (`PARTIAL_MATCH`) holds the beneficiary in `pending_review` waiting for the merchant to `accept` / `reject` via the [signal endpoint](#operation/signalPayoutBeneficiary). A possible AML hit also holds the beneficiary in `pending_review`, but is reviewed by CrissCross's compliance team in our screening provider's tooling — not by the merchant. Beneficiaries are immutable after creation — to change any detail, create a new beneficiary. If a beneficiary with identical details already exists for the caller, the request is soft-blocked with `409` and the existing `payoutBeneficiaryId` is returned in the response body. Pass `allowDuplicate: true` to override and create a new record.

Authentication

AuthorizationBearer

OAuth 2.0 access token issued by the CrissCross authorisation server.

Request

This endpoint expects an object.

merchantIdstringRequiredformat: "uuid"

Merchant ID that will own the beneficiary.

merchantReferencestringRequired>=1 character

Merchant-provided reference for de-duplication and lookup. Persisted and returned on every subsequent read.

recipientobjectRequired

Recipient (payee) details. The type discriminator selects the destination shape.

attributesmap from strings to stringsOptional

Free-form key/value metadata to attach to the beneficiary.

allowDuplicatebooleanOptionalDefaults to false

When true, bypasses the soft-block that returns 409 if a beneficiary with the same identifying details already exists for the caller. Use sparingly — usually you want to reuse the existing beneficiary instead.

Response

Payout beneficiary created. Returned with status: pending_review while account verification and AML pre-screening run; poll until approved before using on a payout.

payoutBeneficiaryIdstringformat: "uuid"

UUID of the beneficiary.

merchantIdstringformat: "uuid"

Merchant ID that owns this beneficiary.

merchantReferencestring

Merchant-provided reference for de-duplication and lookup. Persisted on create and round-trips on every read.

statusenum

Lifecycle status of a payout beneficiary.

pending_review — created, awaiting account verification and AML pre-screening, or held for review. A name-mismatch hold (the receiving network returned a different account holder name) is cleared by the merchant via the signal endpoint (accept / reject). An AML compliance hold is cleared by CrissCross’s compliance team in our screening provider’s tooling — the merchant cannot accept / reject it.
approved — account verification and AML pre-screening both passed; can be referenced from payoutBeneficiaryId on a payout.
rejected — declined by signal, by AML pre-screening, or after exhausting verification retries. Terminal.
failed — verification or screening errored in a non-recoverable way. Use signal: retry to re-run the checks.

recipientobject

Recipient (payee) details. The type discriminator determines which fields are present.

verificationsobject

Outcome of the account-verification + AML pre-screening passes run against the beneficiary.

createdAtdatetime

ISO-8601 timestamp the beneficiary was created.

updatedAtdatetime

ISO-8601 timestamp of the last update.

attributesmap from strings to strings

Free-form key/value metadata attached to the beneficiary at create time.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

409

Conflict Error

422

Unprocessable Entity Error

500

Internal Server Error

Registers a new payout beneficiary. The beneficiary is created with status: pending_review and two independent checks run asynchronously:

Account verification of the destination against the receiving network (e.g. carrier API for mobile money, bank-verification provider for bank accounts). For corridors with internal format rules (e.g. Nigerian NUBAN check-digit) the check-digit pass runs first.
AML pre-screening of the beneficiary against sanctions lists, PEP lists, and internal risk lists.

Beneficiaries are immutable after creation — to change any detail, create a new beneficiary.

$	curl -X POST https://api.crisscross.money/v1/payout-beneficiaries \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
>	"merchantReference": "INV-20240615-001",
>	"recipient": {
>	"type": "bank_account",
>	"accountHolderName": "Jane Doe",
>	"accountNumber": "1234567890",
>	"bankCode": "044",
>	"country": "NGA"
>	}
>	}'

1	{
2	"payoutBeneficiaryId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
3	"merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
4	"merchantReference": "INV-20240615-001",
5	"status": "pending_review",
6	"recipient": {
7	"type": "bank_account",
8	"accountHolderName": "Jane Doe",
9	"accountNumber": "1234567890",
10	"bankCode": "044",
11	"country": "NGA",
12	"phoneNumber": "+2348012345678"
13	},
14	"verifications": {
15	"accountVerification": {
16	"state": "PENDING",
17	"attempts": 1,
18	"provider": "NIBSS",
19	"returnedAccountHolderName": "",
20	"lastError": ""
21	},
22	"amlScreening": {
23	"state": "UNSPECIFIED",
24	"attempts": 1,
25	"reviewReason": ""
26	}
27	},
28	"createdAt": "2024-01-15T09:30:00Z",
29	"updatedAt": "2024-01-15T09:30:00Z",
30	"attributes": {}
31	}