POST Process Cashier Webhook¶
Endpoint¶
POST /cashier/webhook/{provider}
Command¶
ProcessCashierWebhook
Authorization¶
No customer or manager session is required. Security is handled by the payment provider module through webhook signature validation.
Description¶
Receives an incoming payment provider webhook, passes the raw body and headers to the active payment provider instance, stores a provider event, and updates the linked Cashier transaction.
Cashier accepts a provider result only when the module reports
signature_status = 1 (valid). Both unknown and invalid signature states
are rejected with HTTP 401. A valid, confirmed deposit is matched to its
transaction and submitted to the finance ledger through a durable balance
operation. The request can return while status 11 (processing_ledger) is
pending; the ledger result later moves the transaction to credited or
credit_failed after the matching finance trade is confirmed committed in
the separate trading database. Cashier and trading database writes are not one
atomic transaction, and a runtime-cache trade alone does not finalize the
Cashier transaction. If the provider confirms the deposit synchronously during
CreateCashierDeposit, Cashier starts that same ledger operation without
waiting for a webhook.
Repeated events return duplicate: true only when the stored event was
previously processed successfully. A repeated event whose earlier processing
failed returns an error and does not masquerade as a successful duplicate.
Amount/currency mismatches create a failed event; unless the transaction is
already ledger-owned (credited, completed, or processing_ledger), the
transaction moves to manual_review. Ledger-owned statuses are preserved.
The HTTP layer passes transport data to the payment module as:
| Field | Description |
|---|---|
provider |
Provider code from URL |
path |
Request path |
method |
Request method |
headers_json |
JSON string built from parsed request headers |
raw_body |
Original HTTP request body string |
raw_query |
Original URL query string without ? |
content_type |
Request Content-Type header value, when present |
Request Example¶
POST /cashier/webhook/{provider}
Content-Type: application/octet-stream
X-Signature: <provider-signature>
<raw signed payload in the format required by the configured provider module>
Response Example¶
{
"event": {
"id": 21,
"provider": "provider-code",
"event_id": "evt_123",
"transaction_id": 15,
"provider_payment_id": "payment-ref-123",
"payload_json": "{\"event_id\":\"evt_123\",\"status\":\"approved\"}",
"headers_json": "{\"X-Signature\":\"...\"}",
"signature_status": 1,
"processing_status": 1,
"failure_reason": "",
"created_time": 1779270100,
"processed_time": 1779270100
},
"transaction": {
"id": 15,
"customer_id": 5,
"login": 2000009,
"type": 0,
"provider": "provider-code",
"method": "card",
"provider_config_id": 1,
"status": 3,
"provider_payment_id": "payment-ref-123",
"amount": 250.0,
"currency": "USD",
"account_currency": "USD",
"converted_amount": 250.0,
"conversion_rate": 1.0,
"failure_reason": "",
"idempotency_key": "deposit-15",
"comment": "",
"metadata_json": "{}",
"source": 0,
"approved_by": 0,
"approved_time": 0,
"processed_by": 0,
"processed_time": 0,
"reject_reason": "",
"created_time": 1779270000,
"updated_time": 1779270100,
"attributed_manager_id": 12,
"owner_manager_id": 12
},
"data": "OK",
"duplicate": false
}
Response Fields¶
event is the provider-event record (all fields appear in the example):
id, provider, event_id, transaction_id, provider_payment_id,
payload_json, headers_json, signature_status, processing_status,
failure_reason, created_time, and processed_time. For a valid event that
does not match a transaction, transaction_id is 0 and transaction is
omitted. Successful responses also include data: "OK" and duplicate.
Error responses include error and message; they may include the full
transaction when one was matched.
The complete transaction fields and their meanings match the Cashier transaction history response.
Errors¶
| HTTP | Error | Description |
|---|---|---|
400 |
INVALID_DATA |
Provider path parameter is invalid |
400 |
RET_ERR_PARAMS |
Empty webhook payload, or provider-confirmed amount/currency does not match the transaction |
401 |
RET_ERR_PERMISSIONS |
Provider module did not affirm a valid signature (unknown is rejected as well as invalid) |
404 |
RET_ERR_NOTFOUND |
Valid payment reference does not match a Cashier transaction |
5xx |
RET_ERR_NOSERVICE |
No active provider instance could validate and normalize this webhook |
5xx |
RET_TECH_PROBLEM |
Event or transaction state could not be durably recorded |
Notes¶
- Cashier tries active runtime instances for the requested provider until one validates and normalizes the webhook.
- Payment modules are created with their provider config during module creation; webhook requests contain only transport data.
- A concrete webhook body, signature scheme, and normalized event fields are provider-module specific; this page does not define a universal payload.
- The SDK contract requires a module to return normalized event id, payment id, status, signature status, optional amount/currency, and failure details.
- Successful ledger application is deduplicated by transaction-linked finance operation; a webhook acknowledgement is not itself confirmation of final ledger settlement.