Mesta API Reference
Changelog

Sample Webhook payloads

Every webhook Mesta sends uses the same envelope. Only entity.data changes from event to event.

All identifiers, names, amounts and URLs on this page are placeholder values for illustration only — they do not correspond to any real merchant, sender, beneficiary or transaction.

Envelope

{
  "id": "00000000-0000-4000-b000-000000000000",
  "event": "order:success",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000006",
    "type": "order",
    "data": {}
  }
}
FieldDescription
idUnique id for this event. Stable across replays — use it as your idempotency key.
eventThe event name, in <entity>:<action> form.
entity.idId of the object the event is about.
entity.typeOne of order, sender, ubo, beneficiary, fiat_deposit, stablecoin_deposit.
entity.dataA snapshot of that object at the time the event fired.

Request headers

HeaderValue
Content-Typeapplication/json
X-Webhook-SignatureLowercase hex HMAC-SHA256 of the raw request body, signed with your webhook signature key. See Webhook Signature Verification.

Subscribing

Register a webhook with POST /v1/webhooks, passing the event names you want:

{
  "url": "https://example.com/webhooks/mesta",
  "events": ["order:*", "sender:kyb_approved", "fiat_deposit:settled"]
}

order:*, sender:*, ubo:* and beneficiary:* subscribe to every event in that family. You can register up to 5 webhooks.

📘

Fields are omitted, not nulled, when they do not apply

Optional relations and scope-restricted fields may be absent from entity.data entirely. Read defensively rather than asserting on an exact key set.

Order events

Every order event carries the same order snapshot. data.status reflects the merchant-facing order status at the time the event fired, and several internal states collapse onto the same external status.

order:created

The order has been accepted and persisted.

{
  "id": "00000000-0000-4000-b000-000000000001",
  "event": "order:created",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000006",
    "type": "order",
    "data": {
      "id": "00000000-0000-4000-a000-000000000006",
      "version": 1,
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T10:00:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "merchantName": "Example Merchant Inc.",
      "senderId": "00000000-0000-4000-a000-000000000002",
      "senderName": "Example Sender Ltd",
      "beneficiaryId": "00000000-0000-4000-a000-000000000004",
      "beneficiaryName": "Example Beneficiary Ltd",
      "beneficiarySenderId": null,
      "paymentMethodId": "00000000-0000-4000-a000-000000000007",
      "sourceCurrency": "USD",
      "targetCurrency": "GBP",
      "acceptedGrossSourceAmount": "1000.00",
      "targetAmount": "780.00",
      "acceptedQuoteId": "00000000-0000-4000-a000-000000000008",
      "status": "created",
      "customerReferenceId": "EXAMPLE-REF-0001",
      "purpose": "vendor_payment",
      "beneficiaryRelationship": "business_partner",
      "sourceOfFunds": "business_income",
      "documents": [
        {
          "id": "00000000-0000-4000-a000-000000000016",
          "fileName": "example-invoice.pdf",
          "type": "invoice",
          "url": "https://files.example.com/example-invoice.pdf",
          "submittedAt": "2026-01-15T10:00:00.000Z"
        }
      ],
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isSspOrder": false,
      "sspWalletId": null,
      "authConfirmedAt": null,
      "deferredFunding": false,
      "batchOrderId": null,
      "awaitingFundsExpiresAt": null,
      "cancellationRemarks": null,
      "rejectionRemarks": null,
      "disbursementBlockchainHash": null,
      "paymentProcessingPartner": null,
      "uetr": null,
      "imad": null,
      "mt103": null
    }
  }
}

order:awaiting_funds

The order is waiting for the source funds to arrive.

{
  "id": "00000000-0000-4000-b000-000000000002",
  "event": "order:awaiting_funds",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000006",
    "type": "order",
    "data": {
      "id": "00000000-0000-4000-a000-000000000006",
      "version": 1,
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T10:01:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "merchantName": "Example Merchant Inc.",
      "senderId": "00000000-0000-4000-a000-000000000002",
      "senderName": "Example Sender Ltd",
      "beneficiaryId": "00000000-0000-4000-a000-000000000004",
      "beneficiaryName": "Example Beneficiary Ltd",
      "beneficiarySenderId": null,
      "paymentMethodId": "00000000-0000-4000-a000-000000000007",
      "sourceCurrency": "USD",
      "targetCurrency": "GBP",
      "acceptedGrossSourceAmount": "1000.00",
      "targetAmount": "780.00",
      "acceptedQuoteId": "00000000-0000-4000-a000-000000000008",
      "status": "awaiting_funds",
      "customerReferenceId": "EXAMPLE-REF-0001",
      "purpose": "vendor_payment",
      "beneficiaryRelationship": "business_partner",
      "sourceOfFunds": "business_income",
      "documents": [
        {
          "id": "00000000-0000-4000-a000-000000000016",
          "fileName": "example-invoice.pdf",
          "type": "invoice",
          "url": "https://files.example.com/example-invoice.pdf",
          "submittedAt": "2026-01-15T10:00:00.000Z"
        }
      ],
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isSspOrder": false,
      "sspWalletId": null,
      "authConfirmedAt": null,
      "deferredFunding": false,
      "batchOrderId": null,
      "awaitingFundsExpiresAt": "2026-01-16T10:01:00.000Z",
      "cancellationRemarks": null,
      "rejectionRemarks": null,
      "disbursementBlockchainHash": null,
      "paymentProcessingPartner": null,
      "uetr": null,
      "imad": null,
      "mt103": null
    }
  }
}

order:awaiting_funds_timeout

The funding window expired before funds arrived.

{
  "id": "00000000-0000-4000-b000-000000000003",
  "event": "order:awaiting_funds_timeout",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000006",
    "type": "order",
    "data": {
      "id": "00000000-0000-4000-a000-000000000006",
      "version": 1,
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-16T10:01:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "merchantName": "Example Merchant Inc.",
      "senderId": "00000000-0000-4000-a000-000000000002",
      "senderName": "Example Sender Ltd",
      "beneficiaryId": "00000000-0000-4000-a000-000000000004",
      "beneficiaryName": "Example Beneficiary Ltd",
      "beneficiarySenderId": null,
      "paymentMethodId": "00000000-0000-4000-a000-000000000007",
      "sourceCurrency": "USD",
      "targetCurrency": "GBP",
      "acceptedGrossSourceAmount": "1000.00",
      "targetAmount": "780.00",
      "acceptedQuoteId": "00000000-0000-4000-a000-000000000008",
      "status": "awaiting_funds_timeout",
      "customerReferenceId": "EXAMPLE-REF-0001",
      "purpose": "vendor_payment",
      "beneficiaryRelationship": "business_partner",
      "sourceOfFunds": "business_income",
      "documents": [
        {
          "id": "00000000-0000-4000-a000-000000000016",
          "fileName": "example-invoice.pdf",
          "type": "invoice",
          "url": "https://files.example.com/example-invoice.pdf",
          "submittedAt": "2026-01-15T10:00:00.000Z"
        }
      ],
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isSspOrder": false,
      "sspWalletId": null,
      "authConfirmedAt": null,
      "deferredFunding": false,
      "batchOrderId": null,
      "awaitingFundsExpiresAt": "2026-01-16T10:01:00.000Z",
      "cancellationRemarks": null,
      "rejectionRemarks": null,
      "disbursementBlockchainHash": null,
      "paymentProcessingPartner": null,
      "uetr": null,
      "imad": null,
      "mt103": null
    }
  }
}

order:funds_received

The source funds have been credited to the order.

{
  "id": "00000000-0000-4000-b000-000000000004",
  "event": "order:funds_received",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000006",
    "type": "order",
    "data": {
      "id": "00000000-0000-4000-a000-000000000006",
      "version": 1,
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T10:20:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "merchantName": "Example Merchant Inc.",
      "senderId": "00000000-0000-4000-a000-000000000002",
      "senderName": "Example Sender Ltd",
      "beneficiaryId": "00000000-0000-4000-a000-000000000004",
      "beneficiaryName": "Example Beneficiary Ltd",
      "beneficiarySenderId": null,
      "paymentMethodId": "00000000-0000-4000-a000-000000000007",
      "sourceCurrency": "USD",
      "targetCurrency": "GBP",
      "acceptedGrossSourceAmount": "1000.00",
      "targetAmount": "780.00",
      "acceptedQuoteId": "00000000-0000-4000-a000-000000000008",
      "status": "funds_received",
      "customerReferenceId": "EXAMPLE-REF-0001",
      "purpose": "vendor_payment",
      "beneficiaryRelationship": "business_partner",
      "sourceOfFunds": "business_income",
      "documents": [
        {
          "id": "00000000-0000-4000-a000-000000000016",
          "fileName": "example-invoice.pdf",
          "type": "invoice",
          "url": "https://files.example.com/example-invoice.pdf",
          "submittedAt": "2026-01-15T10:00:00.000Z"
        }
      ],
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isSspOrder": false,
      "sspWalletId": null,
      "authConfirmedAt": null,
      "deferredFunding": false,
      "batchOrderId": null,
      "awaitingFundsExpiresAt": null,
      "cancellationRemarks": null,
      "rejectionRemarks": null,
      "disbursementBlockchainHash": null,
      "paymentProcessingPartner": null,
      "uetr": null,
      "imad": null,
      "mt103": null
    }
  }
}

order:in_progress

Screening and/or the transfer legs have started.

{
  "id": "00000000-0000-4000-b000-000000000005",
  "event": "order:in_progress",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000006",
    "type": "order",
    "data": {
      "id": "00000000-0000-4000-a000-000000000006",
      "version": 1,
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T10:25:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "merchantName": "Example Merchant Inc.",
      "senderId": "00000000-0000-4000-a000-000000000002",
      "senderName": "Example Sender Ltd",
      "beneficiaryId": "00000000-0000-4000-a000-000000000004",
      "beneficiaryName": "Example Beneficiary Ltd",
      "beneficiarySenderId": null,
      "paymentMethodId": "00000000-0000-4000-a000-000000000007",
      "sourceCurrency": "USD",
      "targetCurrency": "GBP",
      "acceptedGrossSourceAmount": "1000.00",
      "targetAmount": "780.00",
      "acceptedQuoteId": "00000000-0000-4000-a000-000000000008",
      "status": "in_progress",
      "customerReferenceId": "EXAMPLE-REF-0001",
      "purpose": "vendor_payment",
      "beneficiaryRelationship": "business_partner",
      "sourceOfFunds": "business_income",
      "documents": [
        {
          "id": "00000000-0000-4000-a000-000000000016",
          "fileName": "example-invoice.pdf",
          "type": "invoice",
          "url": "https://files.example.com/example-invoice.pdf",
          "submittedAt": "2026-01-15T10:00:00.000Z"
        }
      ],
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isSspOrder": false,
      "sspWalletId": null,
      "authConfirmedAt": null,
      "deferredFunding": false,
      "batchOrderId": null,
      "awaitingFundsExpiresAt": null,
      "cancellationRemarks": null,
      "rejectionRemarks": null,
      "disbursementBlockchainHash": null,
      "paymentProcessingPartner": null,
      "uetr": null,
      "imad": null,
      "mt103": null
    }
  }
}

order:sent_to_beneficiary

The disbursement has been submitted to the beneficiary.

{
  "id": "00000000-0000-4000-b000-000000000006",
  "event": "order:sent_to_beneficiary",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000006",
    "type": "order",
    "data": {
      "id": "00000000-0000-4000-a000-000000000006",
      "version": 1,
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T11:00:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "merchantName": "Example Merchant Inc.",
      "senderId": "00000000-0000-4000-a000-000000000002",
      "senderName": "Example Sender Ltd",
      "beneficiaryId": "00000000-0000-4000-a000-000000000004",
      "beneficiaryName": "Example Beneficiary Ltd",
      "beneficiarySenderId": null,
      "paymentMethodId": "00000000-0000-4000-a000-000000000007",
      "sourceCurrency": "USD",
      "targetCurrency": "GBP",
      "acceptedGrossSourceAmount": "1000.00",
      "targetAmount": "780.00",
      "acceptedQuoteId": "00000000-0000-4000-a000-000000000008",
      "status": "sent_to_beneficiary",
      "customerReferenceId": "EXAMPLE-REF-0001",
      "purpose": "vendor_payment",
      "beneficiaryRelationship": "business_partner",
      "sourceOfFunds": "business_income",
      "documents": [
        {
          "id": "00000000-0000-4000-a000-000000000016",
          "fileName": "example-invoice.pdf",
          "type": "invoice",
          "url": "https://files.example.com/example-invoice.pdf",
          "submittedAt": "2026-01-15T10:00:00.000Z"
        }
      ],
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isSspOrder": false,
      "sspWalletId": null,
      "authConfirmedAt": null,
      "deferredFunding": false,
      "batchOrderId": null,
      "awaitingFundsExpiresAt": null,
      "cancellationRemarks": null,
      "rejectionRemarks": null,
      "disbursementBlockchainHash": null,
      "paymentProcessingPartner": null,
      "uetr": null,
      "imad": null,
      "mt103": null
    }
  }
}

order:success

The disbursement completed successfully.

{
  "id": "00000000-0000-4000-b000-000000000007",
  "event": "order:success",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000006",
    "type": "order",
    "data": {
      "id": "00000000-0000-4000-a000-000000000006",
      "version": 1,
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T11:30:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "merchantName": "Example Merchant Inc.",
      "senderId": "00000000-0000-4000-a000-000000000002",
      "senderName": "Example Sender Ltd",
      "beneficiaryId": "00000000-0000-4000-a000-000000000004",
      "beneficiaryName": "Example Beneficiary Ltd",
      "beneficiarySenderId": null,
      "paymentMethodId": "00000000-0000-4000-a000-000000000007",
      "sourceCurrency": "USD",
      "targetCurrency": "GBP",
      "acceptedGrossSourceAmount": "1000.00",
      "targetAmount": "780.00",
      "acceptedQuoteId": "00000000-0000-4000-a000-000000000008",
      "status": "success",
      "customerReferenceId": "EXAMPLE-REF-0001",
      "purpose": "vendor_payment",
      "beneficiaryRelationship": "business_partner",
      "sourceOfFunds": "business_income",
      "documents": [
        {
          "id": "00000000-0000-4000-a000-000000000016",
          "fileName": "example-invoice.pdf",
          "type": "invoice",
          "url": "https://files.example.com/example-invoice.pdf",
          "submittedAt": "2026-01-15T10:00:00.000Z"
        }
      ],
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isSspOrder": false,
      "sspWalletId": null,
      "authConfirmedAt": null,
      "deferredFunding": false,
      "batchOrderId": null,
      "awaitingFundsExpiresAt": null,
      "cancellationRemarks": null,
      "rejectionRemarks": null,
      "disbursementBlockchainHash": "0x1111111111111111111111111111111111111111111111111111111111111111",
      "paymentProcessingPartner": null,
      "uetr": null,
      "imad": null,
      "mt103": null
    }
  }
}

order:failed

Screening or disbursement failed. The order will not complete.

{
  "id": "00000000-0000-4000-b000-000000000008",
  "event": "order:failed",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000006",
    "type": "order",
    "data": {
      "id": "00000000-0000-4000-a000-000000000006",
      "version": 1,
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T11:30:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "merchantName": "Example Merchant Inc.",
      "senderId": "00000000-0000-4000-a000-000000000002",
      "senderName": "Example Sender Ltd",
      "beneficiaryId": "00000000-0000-4000-a000-000000000004",
      "beneficiaryName": "Example Beneficiary Ltd",
      "beneficiarySenderId": null,
      "paymentMethodId": "00000000-0000-4000-a000-000000000007",
      "sourceCurrency": "USD",
      "targetCurrency": "GBP",
      "acceptedGrossSourceAmount": "1000.00",
      "targetAmount": "780.00",
      "acceptedQuoteId": "00000000-0000-4000-a000-000000000008",
      "status": "failed",
      "customerReferenceId": "EXAMPLE-REF-0001",
      "purpose": "vendor_payment",
      "beneficiaryRelationship": "business_partner",
      "sourceOfFunds": "business_income",
      "documents": [
        {
          "id": "00000000-0000-4000-a000-000000000016",
          "fileName": "example-invoice.pdf",
          "type": "invoice",
          "url": "https://files.example.com/example-invoice.pdf",
          "submittedAt": "2026-01-15T10:00:00.000Z"
        }
      ],
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isSspOrder": false,
      "sspWalletId": null,
      "authConfirmedAt": null,
      "deferredFunding": false,
      "batchOrderId": null,
      "awaitingFundsExpiresAt": null,
      "cancellationRemarks": null,
      "rejectionRemarks": null,
      "disbursementBlockchainHash": null,
      "paymentProcessingPartner": null,
      "uetr": null,
      "imad": null,
      "mt103": null
    }
  }
}

order:cancelled

The order was cancelled.

{
  "id": "00000000-0000-4000-b000-000000000009",
  "event": "order:cancelled",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000006",
    "type": "order",
    "data": {
      "id": "00000000-0000-4000-a000-000000000006",
      "version": 1,
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T10:05:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "merchantName": "Example Merchant Inc.",
      "senderId": "00000000-0000-4000-a000-000000000002",
      "senderName": "Example Sender Ltd",
      "beneficiaryId": "00000000-0000-4000-a000-000000000004",
      "beneficiaryName": "Example Beneficiary Ltd",
      "beneficiarySenderId": null,
      "paymentMethodId": "00000000-0000-4000-a000-000000000007",
      "sourceCurrency": "USD",
      "targetCurrency": "GBP",
      "acceptedGrossSourceAmount": "1000.00",
      "targetAmount": "780.00",
      "acceptedQuoteId": "00000000-0000-4000-a000-000000000008",
      "status": "cancelled",
      "customerReferenceId": "EXAMPLE-REF-0001",
      "purpose": "vendor_payment",
      "beneficiaryRelationship": "business_partner",
      "sourceOfFunds": "business_income",
      "documents": [
        {
          "id": "00000000-0000-4000-a000-000000000016",
          "fileName": "example-invoice.pdf",
          "type": "invoice",
          "url": "https://files.example.com/example-invoice.pdf",
          "submittedAt": "2026-01-15T10:00:00.000Z"
        }
      ],
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isSspOrder": false,
      "sspWalletId": null,
      "authConfirmedAt": null,
      "deferredFunding": false,
      "batchOrderId": null,
      "awaitingFundsExpiresAt": null,
      "cancellationRemarks": "Cancelled by merchant before funding",
      "rejectionRemarks": null,
      "disbursementBlockchainHash": null,
      "paymentProcessingPartner": null,
      "uetr": null,
      "imad": null,
      "mt103": null
    }
  }
}

order:returned

The funds were returned by the beneficiary bank.

{
  "id": "00000000-0000-4000-b000-000000000011",
  "event": "order:returned",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000006",
    "type": "order",
    "data": {
      "id": "00000000-0000-4000-a000-000000000006",
      "version": 1,
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-17T09:00:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "merchantName": "Example Merchant Inc.",
      "senderId": "00000000-0000-4000-a000-000000000002",
      "senderName": "Example Sender Ltd",
      "beneficiaryId": "00000000-0000-4000-a000-000000000004",
      "beneficiaryName": "Example Beneficiary Ltd",
      "beneficiarySenderId": null,
      "paymentMethodId": "00000000-0000-4000-a000-000000000007",
      "sourceCurrency": "USD",
      "targetCurrency": "GBP",
      "acceptedGrossSourceAmount": "1000.00",
      "targetAmount": "780.00",
      "acceptedQuoteId": "00000000-0000-4000-a000-000000000008",
      "status": "returned",
      "customerReferenceId": "EXAMPLE-REF-0001",
      "purpose": "vendor_payment",
      "beneficiaryRelationship": "business_partner",
      "sourceOfFunds": "business_income",
      "documents": [
        {
          "id": "00000000-0000-4000-a000-000000000016",
          "fileName": "example-invoice.pdf",
          "type": "invoice",
          "url": "https://files.example.com/example-invoice.pdf",
          "submittedAt": "2026-01-15T10:00:00.000Z"
        }
      ],
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isSspOrder": false,
      "sspWalletId": null,
      "authConfirmedAt": null,
      "deferredFunding": false,
      "batchOrderId": null,
      "awaitingFundsExpiresAt": null,
      "cancellationRemarks": null,
      "rejectionRemarks": null,
      "disbursementBlockchainHash": null,
      "paymentProcessingPartner": null,
      "uetr": null,
      "imad": null,
      "mt103": null
    }
  }
}

order:proof_of_payment_received

A proof-of-payment artefact was generated. Only the artefacts produced in that batch are present; mt103, uetr and imad are string references, firc is a file object.

{
  "id": "00000000-0000-4000-b000-000000000012",
  "event": "order:proof_of_payment_received",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000006",
    "type": "order",
    "data": {
      "id": "00000000-0000-4000-a000-000000000006",
      "version": 1,
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T12:00:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "merchantName": "Example Merchant Inc.",
      "senderId": "00000000-0000-4000-a000-000000000002",
      "senderName": "Example Sender Ltd",
      "beneficiaryId": "00000000-0000-4000-a000-000000000004",
      "beneficiaryName": "Example Beneficiary Ltd",
      "beneficiarySenderId": null,
      "paymentMethodId": "00000000-0000-4000-a000-000000000007",
      "sourceCurrency": "USD",
      "targetCurrency": "GBP",
      "acceptedGrossSourceAmount": "1000.00",
      "targetAmount": "780.00",
      "acceptedQuoteId": "00000000-0000-4000-a000-000000000008",
      "status": "success",
      "customerReferenceId": "EXAMPLE-REF-0001",
      "purpose": "vendor_payment",
      "beneficiaryRelationship": "business_partner",
      "sourceOfFunds": "business_income",
      "documents": [
        {
          "id": "00000000-0000-4000-a000-000000000016",
          "fileName": "example-invoice.pdf",
          "type": "invoice",
          "url": "https://files.example.com/example-invoice.pdf",
          "submittedAt": "2026-01-15T10:00:00.000Z"
        }
      ],
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isSspOrder": false,
      "sspWalletId": null,
      "authConfirmedAt": null,
      "deferredFunding": false,
      "batchOrderId": null,
      "awaitingFundsExpiresAt": null,
      "cancellationRemarks": null,
      "rejectionRemarks": null,
      "disbursementBlockchainHash": "0x1111111111111111111111111111111111111111111111111111111111111111",
      "paymentProcessingPartner": null,
      "uetr": "00000000-0000-4000-c000-000000000001",
      "imad": "EXAMPLE-IMAD-0001",
      "mt103": "EXAMPLE-MT103-0001",
      "firc": {
        "fileName": "example-firc.pdf",
        "documentUrl": "https://files.example.com/example-firc.pdf",
        "generatedAt": "2026-01-15T12:00:00.000Z"
      }
    }
  }
}

order:invoice_review_required

Invoice validation requires manual review before the order can proceed.

{
  "id": "00000000-0000-4000-b000-000000000013",
  "event": "order:invoice_review_required",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000006",
    "type": "order",
    "data": {
      "id": "00000000-0000-4000-a000-000000000006",
      "version": 1,
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T10:10:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "merchantName": "Example Merchant Inc.",
      "senderId": "00000000-0000-4000-a000-000000000002",
      "senderName": "Example Sender Ltd",
      "beneficiaryId": "00000000-0000-4000-a000-000000000004",
      "beneficiaryName": "Example Beneficiary Ltd",
      "beneficiarySenderId": null,
      "paymentMethodId": "00000000-0000-4000-a000-000000000007",
      "sourceCurrency": "USD",
      "targetCurrency": "GBP",
      "acceptedGrossSourceAmount": "1000.00",
      "targetAmount": "780.00",
      "acceptedQuoteId": "00000000-0000-4000-a000-000000000008",
      "status": "need_review",
      "customerReferenceId": "EXAMPLE-REF-0001",
      "purpose": "vendor_payment",
      "beneficiaryRelationship": "business_partner",
      "sourceOfFunds": "business_income",
      "documents": [
        {
          "id": "00000000-0000-4000-a000-000000000016",
          "fileName": "example-invoice.pdf",
          "type": "invoice",
          "url": "https://files.example.com/example-invoice.pdf",
          "submittedAt": "2026-01-15T10:00:00.000Z"
        }
      ],
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isSspOrder": false,
      "sspWalletId": null,
      "authConfirmedAt": null,
      "deferredFunding": false,
      "batchOrderId": null,
      "awaitingFundsExpiresAt": null,
      "cancellationRemarks": null,
      "rejectionRemarks": null,
      "disbursementBlockchainHash": null,
      "paymentProcessingPartner": null,
      "uetr": null,
      "imad": null,
      "mt103": null
    }
  }
}

Sender events

Every sender event carries the same sender snapshot. Business senders carry kyb and a null kyc; individual senders carry kyc and a null kyb.

sender:created

A sender record was created.

{
  "id": "00000000-0000-4000-b000-000000000014",
  "event": "sender:created",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000002",
    "type": "sender",
    "data": {
      "id": "00000000-0000-4000-a000-000000000002",
      "version": 1,
      "createdAt": "2026-01-10T09:00:00.000Z",
      "updatedAt": "2026-01-10T09:00:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "type": "business",
      "status": "inactive",
      "fullName": "Example Sender Ltd",
      "firstName": null,
      "middleName": null,
      "lastName": null,
      "birthDate": null,
      "email": "[email protected]",
      "phone": "+12025550100",
      "gender": null,
      "occupation": null,
      "businessType": "corporation",
      "registrationDate": "2020-01-01T00:00:00.000Z",
      "websiteUrl": "https://www.example.com",
      "identificationNumber": "EXAMPLE-TAX-ID-0001",
      "addresses": [
        {
          "street": "1 Example Street",
          "street2": null,
          "city": "Example City",
          "state": "CA",
          "postalCode": "00000",
          "country": "US"
        }
      ],
      "kyb": {
        "status": "unverified",
        "statusUpdatedAt": "2026-01-10T09:00:00.000Z"
      },
      "kyc": {},
      "identity": {},
      "reviewStatus": null,
      "reviewReasonCode": null,
      "tos": null,
      "documents": [],
      "onboardingInfo": {
        "isFinancialInstitution": false
      },
      "configuration": {},
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isMfaConfigured": false,
      "portalAccessStatus": "none",
      "portalInvitedAt": null,
      "portalActivatedAt": null,
      "portalLastLoginAt": null,
      "portalInviteEmail": null,
      "portalInviteTokenExpiresAt": null
    }
  }
}

sender:kyb_pending

Business verification was submitted and is in progress.

{
  "id": "00000000-0000-4000-b000-000000000015",
  "event": "sender:kyb_pending",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000002",
    "type": "sender",
    "data": {
      "id": "00000000-0000-4000-a000-000000000002",
      "version": 1,
      "createdAt": "2026-01-10T09:00:00.000Z",
      "updatedAt": "2026-01-10T09:10:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "type": "business",
      "status": "inactive",
      "fullName": "Example Sender Ltd",
      "firstName": null,
      "middleName": null,
      "lastName": null,
      "birthDate": null,
      "email": "[email protected]",
      "phone": "+12025550100",
      "gender": null,
      "occupation": null,
      "businessType": "corporation",
      "registrationDate": "2020-01-01T00:00:00.000Z",
      "websiteUrl": "https://www.example.com",
      "identificationNumber": "EXAMPLE-TAX-ID-0001",
      "addresses": [
        {
          "street": "1 Example Street",
          "street2": null,
          "city": "Example City",
          "state": "CA",
          "postalCode": "00000",
          "country": "US"
        }
      ],
      "kyb": {
        "status": "pending",
        "statusUpdatedAt": "2026-01-10T09:10:00.000Z"
      },
      "kyc": {},
      "identity": {},
      "reviewStatus": "ai_review_pending",
      "reviewReasonCode": null,
      "tos": null,
      "documents": [],
      "onboardingInfo": {
        "isFinancialInstitution": false
      },
      "configuration": {},
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isMfaConfigured": false,
      "portalAccessStatus": "none",
      "portalInvitedAt": null,
      "portalActivatedAt": null,
      "portalLastLoginAt": null,
      "portalInviteEmail": null,
      "portalInviteTokenExpiresAt": null
    }
  }
}

sender:kyb_approved

Business verification was approved.

{
  "id": "00000000-0000-4000-b000-000000000016",
  "event": "sender:kyb_approved",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000002",
    "type": "sender",
    "data": {
      "id": "00000000-0000-4000-a000-000000000002",
      "version": 1,
      "createdAt": "2026-01-10T09:00:00.000Z",
      "updatedAt": "2026-01-10T11:00:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "type": "business",
      "status": "inactive",
      "fullName": "Example Sender Ltd",
      "firstName": null,
      "middleName": null,
      "lastName": null,
      "birthDate": null,
      "email": "[email protected]",
      "phone": "+12025550100",
      "gender": null,
      "occupation": null,
      "businessType": "corporation",
      "registrationDate": "2020-01-01T00:00:00.000Z",
      "websiteUrl": "https://www.example.com",
      "identificationNumber": "EXAMPLE-TAX-ID-0001",
      "addresses": [
        {
          "street": "1 Example Street",
          "street2": null,
          "city": "Example City",
          "state": "CA",
          "postalCode": "00000",
          "country": "US"
        }
      ],
      "kyb": {
        "status": "approved",
        "statusUpdatedAt": "2026-01-10T11:00:00.000Z"
      },
      "kyc": {},
      "identity": {},
      "reviewStatus": "approved",
      "reviewReasonCode": null,
      "tos": null,
      "documents": [],
      "onboardingInfo": {
        "isFinancialInstitution": false
      },
      "configuration": {},
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isMfaConfigured": false,
      "portalAccessStatus": "none",
      "portalInvitedAt": null,
      "portalActivatedAt": null,
      "portalLastLoginAt": null,
      "portalInviteEmail": null,
      "portalInviteTokenExpiresAt": null
    }
  }
}

sender:kyb_declined

Business verification was declined.

{
  "id": "00000000-0000-4000-b000-000000000017",
  "event": "sender:kyb_declined",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000002",
    "type": "sender",
    "data": {
      "id": "00000000-0000-4000-a000-000000000002",
      "version": 1,
      "createdAt": "2026-01-10T09:00:00.000Z",
      "updatedAt": "2026-01-10T11:00:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "type": "business",
      "status": "inactive",
      "fullName": "Example Sender Ltd",
      "firstName": null,
      "middleName": null,
      "lastName": null,
      "birthDate": null,
      "email": "[email protected]",
      "phone": "+12025550100",
      "gender": null,
      "occupation": null,
      "businessType": "corporation",
      "registrationDate": "2020-01-01T00:00:00.000Z",
      "websiteUrl": "https://www.example.com",
      "identificationNumber": "EXAMPLE-TAX-ID-0001",
      "addresses": [
        {
          "street": "1 Example Street",
          "street2": null,
          "city": "Example City",
          "state": "CA",
          "postalCode": "00000",
          "country": "US"
        }
      ],
      "kyb": {
        "status": "declined",
        "statusUpdatedAt": "2026-01-10T11:00:00.000Z"
      },
      "kyc": {},
      "identity": {},
      "reviewStatus": "rejected",
      "reviewReasonCode": "unable_to_verify_business",
      "tos": null,
      "documents": [],
      "onboardingInfo": {
        "isFinancialInstitution": false
      },
      "configuration": {},
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isMfaConfigured": false,
      "portalAccessStatus": "none",
      "portalInvitedAt": null,
      "portalActivatedAt": null,
      "portalLastLoginAt": null,
      "portalInviteEmail": null,
      "portalInviteTokenExpiresAt": null
    }
  }
}

sender:kyc_pending

Individual verification was submitted and is in progress.

{
  "id": "00000000-0000-4000-b000-000000000018",
  "event": "sender:kyc_pending",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000003",
    "type": "sender",
    "data": {
      "id": "00000000-0000-4000-a000-000000000003",
      "version": 1,
      "createdAt": "2026-01-10T09:00:00.000Z",
      "updatedAt": "2026-01-10T09:10:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "type": "individual",
      "status": "inactive",
      "fullName": null,
      "firstName": "Alex",
      "middleName": null,
      "lastName": "Example",
      "birthDate": "1990-01-01",
      "email": "[email protected]",
      "phone": "+12025550101",
      "gender": "female",
      "occupation": "accountant",
      "businessType": null,
      "registrationDate": null,
      "websiteUrl": null,
      "identificationNumber": "EXAMPLE-ID-0001",
      "addresses": [
        {
          "street": "1 Example Street",
          "street2": null,
          "city": "Example City",
          "state": "CA",
          "postalCode": "00000",
          "country": "US"
        }
      ],
      "kyb": null,
      "kyc": {
        "status": "pending",
        "statusUpdatedAt": "2026-01-10T09:10:00.000Z"
      },
      "identity": {
        "countryCode": "US",
        "documentType": "PASSPORT",
        "documentNumber": "EXAMPLE-DOC-0001",
        "issueDate": "2022-01-01"
      },
      "reviewStatus": "ai_review_pending",
      "reviewReasonCode": null,
      "tos": null,
      "documents": [],
      "onboardingInfo": {
        "isFinancialInstitution": false
      },
      "configuration": {},
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isMfaConfigured": false,
      "portalAccessStatus": "none",
      "portalInvitedAt": null,
      "portalActivatedAt": null,
      "portalLastLoginAt": null,
      "portalInviteEmail": null,
      "portalInviteTokenExpiresAt": null
    }
  }
}

sender:kyc_approved

Individual verification was approved.

{
  "id": "00000000-0000-4000-b000-000000000019",
  "event": "sender:kyc_approved",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000003",
    "type": "sender",
    "data": {
      "id": "00000000-0000-4000-a000-000000000003",
      "version": 1,
      "createdAt": "2026-01-10T09:00:00.000Z",
      "updatedAt": "2026-01-10T11:00:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "type": "individual",
      "status": "inactive",
      "fullName": null,
      "firstName": "Alex",
      "middleName": null,
      "lastName": "Example",
      "birthDate": "1990-01-01",
      "email": "[email protected]",
      "phone": "+12025550101",
      "gender": "female",
      "occupation": "accountant",
      "businessType": null,
      "registrationDate": null,
      "websiteUrl": null,
      "identificationNumber": "EXAMPLE-ID-0001",
      "addresses": [
        {
          "street": "1 Example Street",
          "street2": null,
          "city": "Example City",
          "state": "CA",
          "postalCode": "00000",
          "country": "US"
        }
      ],
      "kyb": null,
      "kyc": {
        "status": "approved",
        "statusUpdatedAt": "2026-01-10T11:00:00.000Z"
      },
      "identity": {
        "countryCode": "US",
        "documentType": "PASSPORT",
        "documentNumber": "EXAMPLE-DOC-0001",
        "issueDate": "2022-01-01"
      },
      "reviewStatus": "approved",
      "reviewReasonCode": null,
      "tos": null,
      "documents": [],
      "onboardingInfo": {
        "isFinancialInstitution": false
      },
      "configuration": {},
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isMfaConfigured": false,
      "portalAccessStatus": "none",
      "portalInvitedAt": null,
      "portalActivatedAt": null,
      "portalLastLoginAt": null,
      "portalInviteEmail": null,
      "portalInviteTokenExpiresAt": null
    }
  }
}

sender:kyc_declined

Individual verification was declined.

{
  "id": "00000000-0000-4000-b000-000000000020",
  "event": "sender:kyc_declined",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000003",
    "type": "sender",
    "data": {
      "id": "00000000-0000-4000-a000-000000000003",
      "version": 1,
      "createdAt": "2026-01-10T09:00:00.000Z",
      "updatedAt": "2026-01-10T11:00:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "type": "individual",
      "status": "inactive",
      "fullName": null,
      "firstName": "Alex",
      "middleName": null,
      "lastName": "Example",
      "birthDate": "1990-01-01",
      "email": "[email protected]",
      "phone": "+12025550101",
      "gender": "female",
      "occupation": "accountant",
      "businessType": null,
      "registrationDate": null,
      "websiteUrl": null,
      "identificationNumber": "EXAMPLE-ID-0001",
      "addresses": [
        {
          "street": "1 Example Street",
          "street2": null,
          "city": "Example City",
          "state": "CA",
          "postalCode": "00000",
          "country": "US"
        }
      ],
      "kyb": null,
      "kyc": {
        "status": "declined",
        "statusUpdatedAt": "2026-01-10T11:00:00.000Z"
      },
      "identity": {
        "countryCode": "US",
        "documentType": "PASSPORT",
        "documentNumber": "EXAMPLE-DOC-0001",
        "issueDate": "2022-01-01"
      },
      "reviewStatus": "rejected",
      "reviewReasonCode": "identity_verification_incomplete",
      "tos": null,
      "documents": [],
      "onboardingInfo": {
        "isFinancialInstitution": false
      },
      "configuration": {},
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isMfaConfigured": false,
      "portalAccessStatus": "none",
      "portalInvitedAt": null,
      "portalActivatedAt": null,
      "portalLastLoginAt": null,
      "portalInviteEmail": null,
      "portalInviteTokenExpiresAt": null
    }
  }
}

sender:tos_link_generated

A Terms of Service acceptance link was issued for the sender.

{
  "id": "00000000-0000-4000-b000-000000000021",
  "event": "sender:tos_link_generated",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000002",
    "type": "sender",
    "data": {
      "id": "00000000-0000-4000-a000-000000000002",
      "version": 1,
      "createdAt": "2026-01-10T09:00:00.000Z",
      "updatedAt": "2026-01-10T11:05:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "type": "business",
      "status": "inactive",
      "fullName": "Example Sender Ltd",
      "firstName": null,
      "middleName": null,
      "lastName": null,
      "birthDate": null,
      "email": "[email protected]",
      "phone": "+12025550100",
      "gender": null,
      "occupation": null,
      "businessType": "corporation",
      "registrationDate": "2020-01-01T00:00:00.000Z",
      "websiteUrl": "https://www.example.com",
      "identificationNumber": "EXAMPLE-TAX-ID-0001",
      "addresses": [
        {
          "street": "1 Example Street",
          "street2": null,
          "city": "Example City",
          "state": "CA",
          "postalCode": "00000",
          "country": "US"
        }
      ],
      "kyb": {
        "status": "approved",
        "statusUpdatedAt": "2026-01-10T11:00:00.000Z"
      },
      "kyc": {},
      "identity": {},
      "reviewStatus": null,
      "reviewReasonCode": null,
      "tos": {
        "status": "pending",
        "link": {
          "url": "https://tos.example.com/example-token",
          "generatedAt": "2026-01-10T11:05:00.000Z",
          "expiresAt": "2026-01-17T11:05:00.000Z",
          "isExpired": false
        }
      },
      "documents": [],
      "onboardingInfo": {
        "isFinancialInstitution": false
      },
      "configuration": {},
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isMfaConfigured": false,
      "portalAccessStatus": "none",
      "portalInvitedAt": null,
      "portalActivatedAt": null,
      "portalLastLoginAt": null,
      "portalInviteEmail": null,
      "portalInviteTokenExpiresAt": null
    }
  }
}

sender:tos_accepted

The sender accepted the Terms of Service.

{
  "id": "00000000-0000-4000-b000-000000000022",
  "event": "sender:tos_accepted",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000002",
    "type": "sender",
    "data": {
      "id": "00000000-0000-4000-a000-000000000002",
      "version": 1,
      "createdAt": "2026-01-10T09:00:00.000Z",
      "updatedAt": "2026-01-10T11:20:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "type": "business",
      "status": "inactive",
      "fullName": "Example Sender Ltd",
      "firstName": null,
      "middleName": null,
      "lastName": null,
      "birthDate": null,
      "email": "[email protected]",
      "phone": "+12025550100",
      "gender": null,
      "occupation": null,
      "businessType": "corporation",
      "registrationDate": "2020-01-01T00:00:00.000Z",
      "websiteUrl": "https://www.example.com",
      "identificationNumber": "EXAMPLE-TAX-ID-0001",
      "addresses": [
        {
          "street": "1 Example Street",
          "street2": null,
          "city": "Example City",
          "state": "CA",
          "postalCode": "00000",
          "country": "US"
        }
      ],
      "kyb": {
        "status": "approved",
        "statusUpdatedAt": "2026-01-10T11:00:00.000Z"
      },
      "kyc": {},
      "identity": {},
      "reviewStatus": null,
      "reviewReasonCode": null,
      "tos": {
        "status": "accepted",
        "acceptedAt": "2026-01-10T11:20:00.000Z",
        "version": "1.0",
        "agreementId": "EXAMPLE-AGREEMENT-0001",
        "link": null
      },
      "documents": [],
      "onboardingInfo": {
        "isFinancialInstitution": false
      },
      "configuration": {},
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isMfaConfigured": false,
      "portalAccessStatus": "none",
      "portalInvitedAt": null,
      "portalActivatedAt": null,
      "portalLastLoginAt": null,
      "portalInviteEmail": null,
      "portalInviteTokenExpiresAt": null
    }
  }
}

sender:activated

The sender is fully cleared and can now transact.

{
  "id": "00000000-0000-4000-b000-000000000023",
  "event": "sender:activated",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000002",
    "type": "sender",
    "data": {
      "id": "00000000-0000-4000-a000-000000000002",
      "version": 1,
      "createdAt": "2026-01-10T09:00:00.000Z",
      "updatedAt": "2026-01-10T11:25:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "type": "business",
      "status": "active",
      "fullName": "Example Sender Ltd",
      "firstName": null,
      "middleName": null,
      "lastName": null,
      "birthDate": null,
      "email": "[email protected]",
      "phone": "+12025550100",
      "gender": null,
      "occupation": null,
      "businessType": "corporation",
      "registrationDate": "2020-01-01T00:00:00.000Z",
      "websiteUrl": "https://www.example.com",
      "identificationNumber": "EXAMPLE-TAX-ID-0001",
      "addresses": [
        {
          "street": "1 Example Street",
          "street2": null,
          "city": "Example City",
          "state": "CA",
          "postalCode": "00000",
          "country": "US"
        }
      ],
      "kyb": {
        "status": "approved",
        "statusUpdatedAt": "2026-01-10T11:00:00.000Z"
      },
      "kyc": {},
      "identity": {},
      "reviewStatus": "approved",
      "reviewReasonCode": null,
      "tos": {
        "status": "accepted",
        "acceptedAt": "2026-01-10T11:20:00.000Z",
        "version": "1.0",
        "agreementId": "EXAMPLE-AGREEMENT-0001",
        "link": null
      },
      "documents": [],
      "onboardingInfo": {
        "isFinancialInstitution": false
      },
      "configuration": {},
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isMfaConfigured": false,
      "portalAccessStatus": "none",
      "portalInvitedAt": null,
      "portalActivatedAt": null,
      "portalLastLoginAt": null,
      "portalInviteEmail": null,
      "portalInviteTokenExpiresAt": null
    }
  }
}

sender:deactivated

The sender was deactivated. This is the only sender event that carries an extra top-level reason field.

{
  "id": "00000000-0000-4000-b000-000000000024",
  "event": "sender:deactivated",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000002",
    "type": "sender",
    "data": {
      "id": "00000000-0000-4000-a000-000000000002",
      "version": 1,
      "createdAt": "2026-01-10T09:00:00.000Z",
      "updatedAt": "2026-01-20T08:00:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "type": "business",
      "status": "inactive",
      "fullName": "Example Sender Ltd",
      "firstName": null,
      "middleName": null,
      "lastName": null,
      "birthDate": null,
      "email": "[email protected]",
      "phone": "+12025550100",
      "gender": null,
      "occupation": null,
      "businessType": "corporation",
      "registrationDate": "2020-01-01T00:00:00.000Z",
      "websiteUrl": "https://www.example.com",
      "identificationNumber": "EXAMPLE-TAX-ID-0001",
      "addresses": [
        {
          "street": "1 Example Street",
          "street2": null,
          "city": "Example City",
          "state": "CA",
          "postalCode": "00000",
          "country": "US"
        }
      ],
      "kyb": {
        "status": "approved",
        "statusUpdatedAt": "2026-01-10T11:00:00.000Z"
      },
      "kyc": {},
      "identity": {},
      "reviewStatus": "human_review_required",
      "reviewReasonCode": null,
      "tos": null,
      "documents": [],
      "onboardingInfo": {
        "isFinancialInstitution": false
      },
      "configuration": {},
      "metadata": {
        "exampleKey": "exampleValue"
      },
      "isMfaConfigured": false,
      "portalAccessStatus": "none",
      "portalInvitedAt": null,
      "portalActivatedAt": null,
      "portalLastLoginAt": null,
      "portalInviteEmail": null,
      "portalInviteTokenExpiresAt": null,
      "reason": "NEW_UBO_ADDED_POST_APPROVAL"
    }
  }
}

UBO events

Beneficial-owner events for a business sender. senderId links the UBO back to its sender.

ubo:created

A beneficial owner was added to a sender.

{
  "id": "00000000-0000-4000-b000-000000000025",
  "event": "ubo:created",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000005",
    "type": "ubo",
    "data": {
      "id": "00000000-0000-4000-a000-000000000005",
      "version": 1,
      "createdAt": "2026-01-10T09:05:00.000Z",
      "updatedAt": "2026-01-10T09:05:00.000Z",
      "senderId": "00000000-0000-4000-a000-000000000002",
      "firstName": "Jordan",
      "lastName": "Example",
      "birthDate": "1985-01-01",
      "email": "[email protected]",
      "phone": "+12025550102",
      "address": {
        "street": "1 Example Street",
        "street2": null,
        "city": "Example City",
        "state": "CA",
        "postalCode": "00000",
        "country": "US"
      },
      "identity": {
        "countryCode": "US",
        "documentType": "PASSPORT",
        "documentNumber": "EXAMPLE-DOC-0002",
        "issueDate": "2022-01-01"
      },
      "identificationNumber": "EXAMPLE-ID-0002",
      "ownershipPercent": 100,
      "pepDeclaration": false,
      "pepQuestionnaire": null,
      "documents": [],
      "kyc": {
        "status": "unverified",
        "statusUpdatedAt": "2026-01-10T09:05:00.000Z"
      },
      "externalRefs": {},
      "decisionSource": null,
      "decision": null,
      "decidedAt": null
    }
  }
}

ubo:verification_pending

The beneficial owner's KYC was submitted and is in progress.

{
  "id": "00000000-0000-4000-b000-000000000026",
  "event": "ubo:verification_pending",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000005",
    "type": "ubo",
    "data": {
      "id": "00000000-0000-4000-a000-000000000005",
      "version": 1,
      "createdAt": "2026-01-10T09:05:00.000Z",
      "updatedAt": "2026-01-10T09:15:00.000Z",
      "senderId": "00000000-0000-4000-a000-000000000002",
      "firstName": "Jordan",
      "lastName": "Example",
      "birthDate": "1985-01-01",
      "email": "[email protected]",
      "phone": "+12025550102",
      "address": {
        "street": "1 Example Street",
        "street2": null,
        "city": "Example City",
        "state": "CA",
        "postalCode": "00000",
        "country": "US"
      },
      "identity": {
        "countryCode": "US",
        "documentType": "PASSPORT",
        "documentNumber": "EXAMPLE-DOC-0002",
        "issueDate": "2022-01-01"
      },
      "identificationNumber": "EXAMPLE-ID-0002",
      "ownershipPercent": 100,
      "pepDeclaration": false,
      "pepQuestionnaire": null,
      "documents": [],
      "kyc": {
        "status": "pending",
        "statusUpdatedAt": "2026-01-10T09:15:00.000Z"
      },
      "externalRefs": {},
      "decisionSource": null,
      "decision": null,
      "decidedAt": null
    }
  }
}

ubo:verification_approved

The beneficial owner was cleared.

{
  "id": "00000000-0000-4000-b000-000000000027",
  "event": "ubo:verification_approved",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000005",
    "type": "ubo",
    "data": {
      "id": "00000000-0000-4000-a000-000000000005",
      "version": 1,
      "createdAt": "2026-01-10T09:05:00.000Z",
      "updatedAt": "2026-01-10T10:45:00.000Z",
      "senderId": "00000000-0000-4000-a000-000000000002",
      "firstName": "Jordan",
      "lastName": "Example",
      "birthDate": "1985-01-01",
      "email": "[email protected]",
      "phone": "+12025550102",
      "address": {
        "street": "1 Example Street",
        "street2": null,
        "city": "Example City",
        "state": "CA",
        "postalCode": "00000",
        "country": "US"
      },
      "identity": {
        "countryCode": "US",
        "documentType": "PASSPORT",
        "documentNumber": "EXAMPLE-DOC-0002",
        "issueDate": "2022-01-01"
      },
      "identificationNumber": "EXAMPLE-ID-0002",
      "ownershipPercent": 100,
      "pepDeclaration": false,
      "pepQuestionnaire": null,
      "documents": [],
      "kyc": {
        "status": "approved",
        "statusUpdatedAt": "2026-01-10T10:45:00.000Z"
      },
      "externalRefs": {},
      "decisionSource": "officer",
      "decision": "approve",
      "decidedAt": "2026-01-10T10:45:00.000Z"
    }
  }
}

ubo:verification_declined

The beneficial owner was declined.

{
  "id": "00000000-0000-4000-b000-000000000028",
  "event": "ubo:verification_declined",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000005",
    "type": "ubo",
    "data": {
      "id": "00000000-0000-4000-a000-000000000005",
      "version": 1,
      "createdAt": "2026-01-10T09:05:00.000Z",
      "updatedAt": "2026-01-10T10:45:00.000Z",
      "senderId": "00000000-0000-4000-a000-000000000002",
      "firstName": "Jordan",
      "lastName": "Example",
      "birthDate": "1985-01-01",
      "email": "[email protected]",
      "phone": "+12025550102",
      "address": {
        "street": "1 Example Street",
        "street2": null,
        "city": "Example City",
        "state": "CA",
        "postalCode": "00000",
        "country": "US"
      },
      "identity": {
        "countryCode": "US",
        "documentType": "PASSPORT",
        "documentNumber": "EXAMPLE-DOC-0002",
        "issueDate": "2022-01-01"
      },
      "identificationNumber": "EXAMPLE-ID-0002",
      "ownershipPercent": 100,
      "pepDeclaration": false,
      "pepQuestionnaire": null,
      "documents": [],
      "kyc": {
        "status": "declined",
        "statusUpdatedAt": "2026-01-10T10:45:00.000Z"
      },
      "externalRefs": {},
      "decisionSource": "officer",
      "decision": "reject",
      "decidedAt": "2026-01-10T10:45:00.000Z"
    }
  }
}

Beneficiary events

beneficiary:created

A beneficiary was created.

{
  "id": "00000000-0000-4000-b000-000000000029",
  "event": "beneficiary:created",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000004",
    "type": "beneficiary",
    "data": {
      "id": "00000000-0000-4000-a000-000000000004",
      "version": 1,
      "createdAt": "2026-01-12T09:00:00.000Z",
      "updatedAt": "2026-01-12T09:00:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "senderId": null,
      "type": "business",
      "status": "inactive",
      "fullName": "Example Beneficiary Ltd",
      "firstName": null,
      "middleName": null,
      "lastName": null,
      "birthDate": null,
      "email": "[email protected]",
      "phone": "+12025550103",
      "address": {
        "street": "2 Example Avenue",
        "street2": null,
        "city": "Example Town",
        "state": null,
        "postalCode": "AA1 1AA",
        "country": "GB"
      },
      "businessType": "corporation",
      "businessRegistrationNumber": "EXAMPLE-REG-0001",
      "beneficiaryRelationship": "business_partner",
      "purposeOfPayment": "vendor_payment",
      "purposeOfPaymentDocument": null,
      "documents": [],
      "identity": null,
      "verification": {
        "status": "pending",
        "statusUpdatedAt": "2026-01-12T09:00:00.000Z"
      },
      "reviewStatus": null,
      "reviewReasonCode": null,
      "metadata": {
        "exampleKey": "exampleValue"
      }
    }
  }
}

beneficiary:verification_approved

The beneficiary passed verification and can receive payouts.

{
  "id": "00000000-0000-4000-b000-000000000030",
  "event": "beneficiary:verification_approved",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000004",
    "type": "beneficiary",
    "data": {
      "id": "00000000-0000-4000-a000-000000000004",
      "version": 1,
      "createdAt": "2026-01-12T09:00:00.000Z",
      "updatedAt": "2026-01-12T10:00:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "senderId": null,
      "type": "business",
      "status": "active",
      "fullName": "Example Beneficiary Ltd",
      "firstName": null,
      "middleName": null,
      "lastName": null,
      "birthDate": null,
      "email": "[email protected]",
      "phone": "+12025550103",
      "address": {
        "street": "2 Example Avenue",
        "street2": null,
        "city": "Example Town",
        "state": null,
        "postalCode": "AA1 1AA",
        "country": "GB"
      },
      "businessType": "corporation",
      "businessRegistrationNumber": "EXAMPLE-REG-0001",
      "beneficiaryRelationship": "business_partner",
      "purposeOfPayment": "vendor_payment",
      "purposeOfPaymentDocument": null,
      "documents": [],
      "identity": null,
      "verification": {
        "status": "approved",
        "statusUpdatedAt": "2026-01-12T10:00:00.000Z"
      },
      "reviewStatus": "approved",
      "reviewReasonCode": null,
      "metadata": {
        "exampleKey": "exampleValue"
      }
    }
  }
}

beneficiary:verification_declined

The beneficiary failed verification.

{
  "id": "00000000-0000-4000-b000-000000000031",
  "event": "beneficiary:verification_declined",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000004",
    "type": "beneficiary",
    "data": {
      "id": "00000000-0000-4000-a000-000000000004",
      "version": 1,
      "createdAt": "2026-01-12T09:00:00.000Z",
      "updatedAt": "2026-01-12T10:00:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "senderId": null,
      "type": "business",
      "status": "inactive",
      "fullName": "Example Beneficiary Ltd",
      "firstName": null,
      "middleName": null,
      "lastName": null,
      "birthDate": null,
      "email": "[email protected]",
      "phone": "+12025550103",
      "address": {
        "street": "2 Example Avenue",
        "street2": null,
        "city": "Example Town",
        "state": null,
        "postalCode": "AA1 1AA",
        "country": "GB"
      },
      "businessType": "corporation",
      "businessRegistrationNumber": "EXAMPLE-REG-0001",
      "beneficiaryRelationship": "business_partner",
      "purposeOfPayment": "vendor_payment",
      "purposeOfPaymentDocument": null,
      "documents": [],
      "identity": null,
      "verification": {
        "status": "declined",
        "statusUpdatedAt": "2026-01-12T10:00:00.000Z"
      },
      "reviewStatus": "rejected",
      "reviewReasonCode": null,
      "metadata": {
        "exampleKey": "exampleValue"
      }
    }
  }
}

Deposit events

fiat_deposit:settled

A fiat deposit has settled and been credited. merchantTransactionId matches a row in GET /v1/merchant/transactions; feeMerchantTransactionId is present only when a non-zero deposit fee was charged.

{
  "id": "00000000-0000-4000-b000-000000000032",
  "event": "fiat_deposit:settled",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000010",
    "type": "fiat_deposit",
    "data": {
      "id": "00000000-0000-4000-a000-000000000010",
      "createdAt": "2026-01-14T08:00:00.000Z",
      "updatedAt": "2026-01-14T08:45:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "senderId": "00000000-0000-4000-a000-000000000002",
      "depositorId": "00000000-0000-4000-a000-000000000014",
      "depositBankAccountId": "00000000-0000-4000-a000-000000000015",
      "transactionId": "00000000-0000-4000-a000-000000000009",
      "amount": "1000.00",
      "currency": "USD",
      "status": "completed",
      "isSsp": false,
      "depositFee": "1.50",
      "netAmount": "998.50",
      "merchantTransactionId": "00000000-0000-4000-a000-000000000012",
      "feeMerchantTransactionId": "00000000-0000-4000-a000-000000000013"
    }
  }
}

stablecoin_deposit:settled

A stablecoin deposit has settled and been credited. blockchainHash is the on-chain hash of the crediting transaction — use it to reconcile against your own records.

{
  "id": "00000000-0000-4000-b000-000000000033",
  "event": "stablecoin_deposit:settled",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000011",
    "type": "stablecoin_deposit",
    "data": {
      "id": "00000000-0000-4000-a000-000000000011",
      "createdAt": "2026-01-14T12:00:00.000Z",
      "updatedAt": "2026-01-14T12:05:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "senderId": "00000000-0000-4000-a000-000000000002",
      "transactionId": "00000000-0000-4000-a000-000000000009",
      "amount": "1000.00",
      "currency": "USDC",
      "status": "completed",
      "isSsp": false,
      "isPooled": false,
      "blockchainHash": "0x1111111111111111111111111111111111111111111111111111111111111111"
    }
  }
}

stablecoin_deposit:rejected

A stablecoin deposit failed compliance review and was not credited.

{
  "id": "00000000-0000-4000-b000-000000000034",
  "event": "stablecoin_deposit:rejected",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000011",
    "type": "stablecoin_deposit",
    "data": {
      "id": "00000000-0000-4000-a000-000000000011",
      "createdAt": "2026-01-14T12:00:00.000Z",
      "updatedAt": "2026-01-14T12:10:00.000Z",
      "merchantId": "00000000-0000-4000-a000-000000000001",
      "senderId": "00000000-0000-4000-a000-000000000002",
      "transactionId": "00000000-0000-4000-a000-000000000009",
      "amount": "1000.00",
      "currency": "USDC",
      "status": "rejected",
      "isSsp": false,
      "isPooled": false,
      "blockchainHash": "0x1111111111111111111111111111111111111111111111111111111111111111"
    }
  }
}

Updated 10 days ago

Did this page help you?

Updated 10 days ago

Did this page help you?