Webhook events

The payment, payment destination, and customer event types, delivery headers, and payload.

Each delivery is a single event for one association. Use the X-Webhook-Event header as the reliable event discriminator.

Event types

Event type (type)	X-Webhook-Event	When it is sent
IntentInitiated	intent.initiated	A payment was initiated.
IntentProcessing	intent.processing	A payment is being processed.
IntentSuccessful	intent.successful	A payment completed successfully.
IntentFailed	intent.failed	A payment failed.
IntentRefunding	intent.refunding	A refund is in progress.
IntentRefunded	intent.refunded	A payment was refunded.
IntentRefundFailed	intent.refund.failed	A refund failed.
IntentCancelled	intent.cancelled	A payment was cancelled.
Beneficiary_PaymentDestination_Approved	beneficiary.payment_destination.approved	A payment destination you submitted for verification was approved.
Beneficiary_PaymentDestination_Rejected	beneficiary.payment_destination.rejected	A payment destination you submitted for verification was rejected.
Customer_Verified	customer.verified	A provider verified a customer you registered.
Customer_Rejected	customer.rejected	A provider rejected a customer you registered.

These are the values you subscribe to when you create a webhook. IntentSuccessful and IntentFailed correspond to a transaction reaching completed and failed respectively.

Delivery headers

Every delivery is an HTTP POST with a JSON body and these headers:

• X-Webhook-Event: the dotted event key, for example intent.successful.
• X-Zeam-Signature: sha256=<hex>, an HMAC of the body keyed on X-Webhook-Id. See Security.
• X-Association-Id: the association the event belongs to.
• X-Webhook-Id: a unique delivery id. Also the HMAC key. Use it to de-duplicate retries.
• X-Webhook-Ts: delivery timestamp as Unix milliseconds (UTC). Use it to reject stale deliveries. See Security.
• Content-Type: application/json; charset=utf-8.

Payload

type · string

The event type, as the name in the table above (for example IntentSuccessful). The X-Webhook-Event header carries the dotted key.

intentId · string

The payment intent identifier. For payment destination events it is the destination id; for customer events it is all zeros.

associationId · string

The association the event belongs to.

description · string

A human-readable description of the event.

created · string

ISO 8601 timestamp of when the event was created.

metaData · object

Event-specific detail. The shape for each family of events is below; read fields defensively.

externalReference · string | null

For a payment you submitted, the transactionId from your request. For a provider on-ramp payment, an id Zeam assigned; match those on metaData.data.transactionDetails instead. For customer events, the customerId you registered.

transactionHash · string | null

The Stellar transaction hash, once the payment is on-chain.

source · string | null

Identifies the flow that produced the event. Treat it as an opaque label.

Example delivery

{
  "type": "IntentSuccessful",
  "intentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "associationId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "description": "Payment intent completed successfully.",
  "created": "2026-01-15T10:32:07.512+00:00",
  "metaData": {
    "association_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "transaction_intent_status": "Completed",
    "data": {}
  },
  "externalReference": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "transactionHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "source": "Business.Me2Me.SingleAsset"
}

Payment events

For the Intent* events, metaData carries:

• association_id: the association the payment belongs to.
• transaction_intent_status: the intent’s state: Created, Executing, Processing, Completed, Failed, Reversing, Reversed, or RequiresManualIntervention.
• data: {} for payments you submitted. For provider on-ramp payments, a summary of the payout:

metaData.data.direction · string

Receive: the fees were taken from the payment before it reached your wallet.

metaData.data.netAmount · string

What lands in your wallet, to 7 decimal places.

metaData.data.totalFees · string

The fees, to 7 decimal places. netAmount plus totalFees is what the customer paid.

metaData.data.assetCode · string

The asset of netAmount and totalFees, for example ZARZ.

metaData.data.transactionDetails · object

type is OnRamp. onrampReference is the reference you registered that the payment arrived on (for EasyPay, the EasyPay number), and paymentReference is the provider’s reference for this payment, when it has one.

Example provider on-ramp metaData

{
  "association_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "transaction_intent_status": "Completed",
  "data": {
    "direction": "Receive",
    "netAmount": "97.5000000",
    "totalFees": "2.5000000",
    "assetCode": "ZARZ",
    "transactionDetails": {
      "type": "OnRamp",
      "onrampReference": "9505617000000001",
      "paymentReference": "REF-001"
    }
  }
}

An IntentFailed raised because a payment could not be accepted for processing at all is the exception: its metaData is {} and its externalReference is null. Key on intentId and the X-Webhook-Event header, and read metaData defensively.

Payment destination events

For Beneficiary_PaymentDestination_Approved and Beneficiary_PaymentDestination_Rejected, intentId is the payment destination id, externalReference and transactionHash are null, and metaData carries beneficiaryId, destinationId, method, decision, note, occurredAt, and the beneficiary’s classification.

Customer events

Customer_Verified and Customer_Rejected are not about a payment, so intentId is all zeros and transactionHash is null. externalReference and metaData.customerId carry the customerId you registered, and metaData.status is Verified or Rejected.

Example customer delivery

{
  "type": "Customer_Verified",
  "intentId": "00000000-0000-0000-0000-000000000000",
  "associationId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "description": "Customer verified",
  "created": "2026-10-02T12:00:00+00:00",
  "metaData": { "customerId": "cust-1001", "status": "Verified" },
  "externalReference": "cust-1001",
  "transactionHash": null,
  "source": "connect"
}

Reconcile the event

For a payment you submitted, the event does not include the amount. Look the payment up with GET /v1/transactions/{transactionId}, using the transactionRecordId you received in the 202 response, and act on the authoritative record.

A provider on-ramp payment has no transaction record. Its amounts are in metaData.data on its lifecycle events, and transactionDetails.onrampReference tells you which of your references it arrived on. Once it settles, the payout also appears in the wallet’s balance and statement.