Event reference

The event types Soxara emits today. This list is deliberately short — we only document events that actually fire, so you never subscribe to something that never arrives. More land here as they ship.

Payment events

Event	When it fires
`payment.completed`	A payment settled — a payment-link payment cleared, or a recurring charge succeeded. Funds are credited to your merchant wallet.
`payment.failed`	A payment did not settle — card declined, MoMo timed out / cancelled, insufficient wallet balance, or an expired link. No funds moved.

That’s the full set right now. (Internally, a link that expires also emits payment.failed — you reconcile on “did the money land?”, not the specific failure mode.)

These fire for every payment path: hosted-checkout link payments, sandbox simulate calls, and recurring mandate charges — all the same two events, same shape.

Payload

Both events share one shape (see Overview for the full field table):

{
  "type": "payment.completed",
  "createdAt": "2026-07-04T18:00:00Z",
  "data": {
    "payment": {
      "id": "…",
      "amount": 1200,
      "currency": "USD",
      "status": "completed",
      "payment_method": "card",
      "environment": "test",
      "mandate_id": "…",              // set on a recurring charge; null for a link payment
      "payment_link_id": null,        // set on a link payment; null for a charge
      "idempotency_key": "sub_42:2026-07",  // your key — the correlation handle
      "created_at": "…"
    },
    "link": { … }                     // a snapshot of the payment link, when the payment is link-bound
  }
}

Correlating an event back to your records

Recurring charges: match on data.payment.idempotency_key (the cycle key you sent on POST /v1/api/charges) or data.payment.mandate_id.
Payment links: match on data.link.id / data.link.link_code, or the idempotency key you set at link creation.

Coming later

Refunds, disputes, and richer lifecycle events will appear here when they’re actually emitted — not before. If your integration needs one that isn’t listed, tell us at [email protected] so we prioritise it.

Signature verification Testing webhooks