Signal Payout Beneficiary

Drives a merchant-facing lifecycle transition on a payout beneficiary.

accept and reject are decisions about the account-name verification only — the merchant is confirming (or declining) a name mismatch returned by the receiving network. They are not valid against an AML compliance hold.

AML screening decisions are made by CrissCross’s compliance team in our screening provider’s tooling, not by the merchant. When verifications.amlScreening.state is REVIEW, the merchant waits; sending accept or reject against that hold returns 422 INVALID_SIGNAL_FOR_STATUS. The beneficiary moves to approved once compliance clears it, or to rejected if compliance declines.

accept — clears a PARTIAL_MATCH account-name hold (the merchant confirms the small name difference is acceptable). If AML is already clear the beneficiary moves to approved. Not valid against an AML REVIEW hold.
reject — declines a PARTIAL_MATCH account-name hold; terminal rejected. Not valid against an AML REVIEW hold.
retry — re-runs both account verification and AML pre-screening for a beneficiary in a recoverable state (e.g. failed, or one stuck because of a transient provider error). Valid in any non-terminal state.

Sending a signal that is not valid for the current status (e.g. retry on an approved beneficiary, or accept/reject against an AML REVIEW hold) is rejected with 422.

Drives a merchant-facing lifecycle transition on a payout beneficiary. `accept` and `reject` are decisions about the **account-name verification only** — the merchant is confirming (or declining) a name mismatch returned by the receiving network. They are **not** valid against an AML compliance hold. **AML screening decisions are made by CrissCross's compliance team in our screening provider's tooling, not by the merchant.** When `verifications.amlScreening.state` is `REVIEW`, the merchant waits; sending `accept` or `reject` against that hold returns `422 INVALID_SIGNAL_FOR_STATUS`. The beneficiary moves to `approved` once compliance clears it, or to `rejected` if compliance declines. - `accept` — clears a `PARTIAL_MATCH` account-name hold (the merchant confirms the small name difference is acceptable). If AML is already clear the beneficiary moves to `approved`. Not valid against an AML `REVIEW` hold. - `reject` — declines a `PARTIAL_MATCH` account-name hold; terminal `rejected`. Not valid against an AML `REVIEW` hold. - `retry` — re-runs **both** account verification and AML pre-screening for a beneficiary in a recoverable state (e.g. `failed`, or one stuck because of a transient provider error). Valid in any non-terminal state. Sending a signal that is not valid for the current status (e.g. `retry` on an `approved` beneficiary, or `accept`/`reject` against an AML `REVIEW` hold) is rejected with `422`.

Authentication

AuthorizationBearer

OAuth 2.0 access token issued by the CrissCross authorisation server.

Path parameters

payoutBeneficiaryIdstringRequiredformat: "uuid"

UUID of the payout beneficiary.

Request

This endpoint expects an object.

signalenumRequired

Lifecycle signal to apply.

accept — clear a PARTIAL_MATCH account-name hold (the merchant confirms the small name difference is acceptable). Moves the beneficiary to approved once AML is also clear. Not valid against an AML REVIEW hold — compliance reviews are decided by CrissCross’s compliance team, not by the merchant.
reject — decline a PARTIAL_MATCH account-name hold. Terminal rejected. Not valid against an AML REVIEW hold — compliance reviews are decided by CrissCross’s compliance team, not by the merchant.
retry — re-run both account verification and AML pre-screening for a beneficiary in a recoverable state. Valid in any non-terminal state.

reasonstringOptional<=500 characters

Optional human-readable reason recorded with the transition (e.g. why a partial match was accepted).

Response

Signal applied. Returns the updated beneficiary.

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

404

Not Found Error

422

Unprocessable Entity Error

500

Internal Server Error

Drives a merchant-facing lifecycle transition on a payout beneficiary.

accept — clears a PARTIAL_MATCH account-name hold (the merchant confirms the small name difference is acceptable). If AML is already clear the beneficiary moves to approved. Not valid against an AML REVIEW hold.
reject — declines a PARTIAL_MATCH account-name hold; terminal rejected. Not valid against an AML REVIEW hold.
retry — re-runs both account verification and AML pre-screening for a beneficiary in a recoverable state (e.g. failed, or one stuck because of a transient provider error). Valid in any non-terminal state.

Sending a signal that is not valid for the current status (e.g. retry on an approved beneficiary, or accept/reject against an AML REVIEW hold) is rejected with 422.

$	curl -X POST https://api.crisscross.money/v1/payout-beneficiaries/f47ac10b-58cc-4372-a567-0e02b2c3d479/signal \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"signal": "accept"
>	}'

1	{
2	"payoutBeneficiaryId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
3	"merchantId": "a12b3c4d-56e7-890f-1234-56789abcdef0",
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": "PARTIAL_MATCH",
17	"attempts": 2,
18	"provider": "BankVerifyAPI",
19	"returnedAccountHolderName": "Janet Doe",
20	"lastError": ""
21	},
22	"amlScreening": {
23	"state": "CLEARED",
24	"attempts": 1,
25	"reviewReason": ""
26	}
27	},
28	"createdAt": "2024-01-15T09:30:00Z",
29	"updatedAt": "2024-01-15T10:00:00Z",
30	"attributes": {}
31	}