ConceptsWebhooks
Payload reference
The JSON shape of every webhook envelope and entity. Use this to write strongly-typed handlers.
Every webhook MintCash sends shares a common envelope. The variable part is data, whose shape is determined by type.
Envelope
| Field | Type | Notes |
|---|---|---|
eventId | string (UUID) | Stable across retries of the same event. Use as your dedupe key. |
event | string | The transition: payment.succeeded, subscription.failed, etc. |
type | string | Determines the shape of data: payment, subscription, or refund. |
apiVersion | string | Webhook schema version (2026-05-01). |
environment | string | live or test. |
createdAt | string (ISO8601) | When the event was emitted. |
data | object | The entity. Shape depends on type. |
Payment payload (type: "payment")
Fires for: payment.created, payment.pending, payment.authorized, payment.succeeded, payment.failed, payment.voided.
{
"eventId": "01HXX...",
"event": "payment.succeeded",
"type": "payment",
"apiVersion": "2026-05-01",
"environment": "live",
"createdAt": "2026-05-22T14:32:08.412Z",
"data": {
"id": "pmt_01HXX...",
"externalId": "order_123",
"status": "succeeded",
"amount": 49.99,
"currency": "USD",
"providerTransactionId": "provider_txn_abc",
"failureCode": null,
"failureMessage": null,
"amountRefunded": 0,
"amountRefundable": 49.99,
"customer": {
"id": "cust_01HXX...",
"externalId": "cust_42",
"email": "buyer@example.com",
"name": "Jane Doe",
"phone": "+15551234567"
},
"billingAddress": {
"country": "US",
"postalCode": "10001",
"name": "Jane Doe",
"line1": "1 Madison Ave",
"line2": null,
"city": "New York",
"state": "NY"
},
"card": {
"brand": "mastercard",
"last4": "0000",
"expMonth": 12,
"expYear": 2030
},
"cardToken": "tok_01HXX...",
"createdAt": "2026-05-22T14:31:50.001Z",
"updatedAt": "2026-05-22T14:32:08.412Z"
}
}type PaymentEvent = {
eventId: string;
event:
| "payment.created"
| "payment.pending"
| "payment.authorized"
| "payment.succeeded"
| "payment.failed"
| "payment.voided";
type: "payment";
apiVersion: string;
environment: "live" | "test";
createdAt: string;
data: {
id: string;
externalId: string;
status:
| "created"
| "pending"
| "authorized"
| "succeeded"
| "failed"
| "voided";
amount: number; // major units
currency: string;
providerTransactionId: string | null;
failureCode: string | null;
failureMessage: string | null;
amountRefunded: number;
amountRefundable: number;
customer: Customer;
billingAddress: Address | null;
card: Card | null;
cardToken: string | null;
createdAt: string;
updatedAt: string;
};
};Refund payload (type: "payment", refund events)
Fires for: payment.partially_refunded, payment.refunded, payment.refund_failed.
{
"eventId": "01HXX...",
"event": "payment.refunded",
"type": "payment",
"apiVersion": "2026-05-01",
"environment": "live",
"createdAt": "2026-05-22T16:10:11.000Z",
"data": {
"id": "pmt_01HXX...",
"externalId": "order_123",
"status": "refunded",
"amountRefunded": 49.99,
"amountRefundable": 0,
"refund": {
"id": "rfd_01HXX...",
"externalId": "refund_order_123_full",
"amount": 49.99,
"currency": "USD",
"reason": "customer_request",
"status": "succeeded",
"createdAt": "2026-05-22T16:09:45.000Z"
}
}
}Subscription payload (type: "subscription")
Fires for: subscription.succeeded, subscription.failed, subscription.cancelled.
{
"eventId": "01HXX...",
"event": "subscription.succeeded",
"type": "subscription",
"apiVersion": "2026-05-01",
"environment": "live",
"createdAt": "2026-05-22T08:00:00.000Z",
"data": {
"id": "sub_01HXX...",
"externalId": "sub_cust42_plan_pro",
"status": "active",
"amount": 19.99,
"currency": "USD",
"billingIntervalDays": 30,
"currentPeriodEnd": "2026-06-21T08:00:00.000Z",
"customer": {
"id": "cust_01HXX...",
"externalId": "cust_42",
"email": "buyer@example.com",
"name": "Jane Doe"
},
"lastPayment": {
"id": "pmt_01HXX...",
"status": "succeeded",
"amount": 19.99
}
}
}