Webhook Events

This page covers which events CrissCross sends and what each one contains. For subscribing an endpoint, verifying signatures, retries, and replay, see Webhooks.

Event Types

CrissCross sends webhook events for transactions (payments in), refunds, payouts (payments out), payout beneficiaries, and rate locks.

Transaction event types:

Refund event types:

Payout event types:

Payout beneficiary event types:

Rate lock event types:

Rate lock events are the exception on this page: they carry a rate-lock payload wrapped in an envelope, { eventType, timestamp, payload }, so for those two events the event type is readable from the body. See Rate Locks and the Rate Lock Webhooks API reference for the schema. Every other event on this page uses one of the bodies below, which carry no envelope.

Body Types

Every event above except the rate lock ones sends one of four bodies, delivered as the HTTP body with no envelope around it. Which one you receive depends on the event:

Transaction body

The transaction the event is about. For a refund.* event this is the refund itself; for transaction.refunded it is the original payment.

Nullable fields arrive as an explicit null when unset. Optional fields are left out of the body entirely. Parse accordingly.

FX payments carry collection, fxMidRate, fxAllInRate, fxMarkupBps, and fxFee as well. See Adaptive Currency Conversion.

authState

authState describes the current state in more detail. What it carries depends on the status — when it is present, state and transitionedAt always are:

Things to watch:

• REFUNDED bodies have no authState at all. A handler that assumes the key exists will break on transaction.refunded.
• ERRORED reports authState.state as error, not errored. Match on the value, not on the event name.
• code uses different values for FAILED than for ERRORED — authentication failure codes versus error codes. See Error Codes.
• The top-level message is not a failure reason. On FAILED, ERRORED, CANCELLED, EXPIRED, SETTLED, and REFUNDED it is always the string "Transaction queried successfully". Take the reason from authState.message and authState.code.
• SETTLED carries no settlement identifier. Use the settlement endpoints to find which settlement a transaction landed in.

Late payment summary

Sent when a payment arrives after its order was already cancelled or expired. It is a summary, not the full transaction — call Retrieve Payment Status if you need the rest.

Release summary

Sent when a held transaction is released and treated as completed.

Beneficiary

The payout beneficiary the event is about. status always matches the event.

Account-name verification runs for mobile money only. A bank account is screened but not name-checked, so its validation stays at verified: false, state: "PENDING", attempts: 0 even once the beneficiary is validated — read status, not validation.verified, to decide whether it can be paid out to. For the same reason payout_beneficiary.partial_match only ever fires for mobile money.

Example Webhook Payloads

Every delivery arrives with the same headers, and none of them names the event. For the bodies below the event type is not in the body either, so route by subscribing each endpoint to the specific events you want. (Rate lock events are the exception — see above.)

content-type:   application/json
svix-id:        msg_EXAMPLE0000000000000000000
svix-timestamp: 1753093800
svix-signature: v1,EXAMPLE_BASE64_SIGNATURE=

The bodies below are complete, exactly as delivered.

A completed transaction (transaction.completed):

{
  "transactionId": "019b024f-8c57-777f-a97c-fa21a2bdbb40",
  "status": "COMPLETED",
  "message": "Collection successful",
  "merchantReference": "ORDER-2026-0142",
  "identifiers": {
    "payerId": "019b024f-1a2b-7cde-8f01-223344556677",
    "sessionId": "5f1a3b6c-2d4e-4f8a-9b1c-7d2e3f4a5b6c"
  },
  "paymentAttributes": {
    "orderSource": "web",
    "merchant_type": "real"
  },
  "paymentMethodId": "mobilemoney",
  "processorName": "example-processor",
  "processorReference": "PROC_REF_123",
  "financialTransactionReference": null,
  "currentAttemptId": "019b024f-9e8d-7c6b-a5f4-332211009988",
  "sessionId": "5f1a3b6c-2d4e-4f8a-9b1c-7d2e3f4a5b6c",
  "authState": {
    "state": "completed",
    "message": "Collection successful",
    "transitionedAt": "2026-07-21T10:30:00.000Z"
  }
}

A completed payout (payout.completed):

{
  "transactionId": "019b024f-8c57-777f-a97c-fa21a2bdbb40",
  "status": "COMPLETED",
  "message": "Payout completed",
  "merchantReference": "PAYOUT_550e8400-e29b-41d4-a716-446655440000",
  "paymentMethodId": "mobilemoney",
  "identifiers": {},
  "paymentAttributes": { "merchant_type": "real" },
  "processorReference": "LK_REF_123",
  "currentAttemptId": "ATTEMPT_456",
  "authState": {
    "state": "completed",
    "transitionedAt": "2025-07-21T11:00:00.000Z",
    "message": "Payout completed"
  }
}

A completed refund (refund.completed). This is the refund’s own transaction, not the original payment:

{
  "transactionId": "019b0250-4c11-7a3e-b8d2-77aa11bc9f04",
  "status": "COMPLETED",
  "message": "Refund successful",
  "merchantReference": "ORDER-2026-0142",
  "identifiers": {
    "payerId": "019b024f-1a2b-7cde-8f01-223344556677",
    "sessionId": "5f1a3b6c-2d4e-4f8a-9b1c-7d2e3f4a5b6c"
  },
  "paymentAttributes": {
    "orderSource": "web",
    "merchant_type": "real"
  },
  "paymentMethodId": "mobilemoney",
  "processorName": "example-processor",
  "processorReference": "PROC_REF_456",
  "financialTransactionReference": null,
  "currentAttemptId": "019b0250-4c11-7a3e-b8d2-88bb22cd0a15",
  "sessionId": "5f1a3b6c-2d4e-4f8a-9b1c-7d2e3f4a5b6c",
  "authState": {
    "state": "completed",
    "message": "Refund successful",
    "transitionedAt": "2026-07-22T09:12:44.000Z"
  }
}

A refund copies the original payment’s merchantReference, identifiers, paymentMethodId, and paymentAttributes, but it is its own transaction: transactionId, message, processorReference, currentAttemptId, and authState are the refund’s, not the payment’s. There is no original-transaction id or transaction type in the body. So:

• Match a refund to its payment from your own records: when you create the refund, persist the returned transactionId together with the response’s originalTransactionId, and look the webhook’s transactionId up against that. merchantReference and identifiers.sessionId are not reliable keys — a session can hold more than one refundable transaction.
• Tell the two records apart by transactionId — keying on merchantReference alone risks double-counting.
• Give refund.* its own endpoint. Nothing in the body separates it from transaction.*.

A late payment that arrived against a cancelled order and was automatically refunded (transaction.auto_refunded). transaction.held_pending_review and transaction.auto_refund_failed carry the same two fields:

{
  "transactionId": "019b024f-8c57-777f-a97c-fa21a2bdbb40",
  "reason": "merchant_cancellation"
}

A held transaction that was released (transaction.released) — the same shape without reason:

{
  "transactionId": "019b024f-8c57-777f-a97c-fa21a2bdbb40"
}

A mobile money beneficiary that passed validation and screening (payout_beneficiary.validated). All four payout_beneficiary.* events carry this same object, with status matching the event:

{
  "payoutBeneficiaryId": "0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a",
  "merchantId": "ACME",
  "status": "PAYOUT_BENEFICIARY_STATUS_VALIDATED",
  "type": "PAYOUT_BENEFICIARY_TYPE_MOBILE_MONEY",
  "country": "KE",
  "currency": "KES",
  "validation": {
    "verified": true,
    "validatedAccountHolderName": "A Mwangi",
    "returnedAccountHolderName": "A Mwangi",
    "state": "VERIFIED",
    "attempts": 1
  },
  "amlScreening": {
    "state": "AML_SCREENING_STATE_CLEARED",
    "screeningId": "scr_01HX5GMR3K8YBQ5VCRD7P3F9Z2",
    "attempts": 1
  },
  "updatedAt": "2026-06-02T10:30:14.000Z"
}

status, type, and amlScreening.state are prefixed enum names rather than bare words, so compare against the full string — see Beneficiary for the values. The error and reason fields are omitted when empty, so expect them on partial_match, screening_review, and rejected rather than on validated.