Skip to content

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.