Real-Time Webhook Notifications
Webhooks & Cryptographic Signature Verification
SofizPay sends reliable server-to-server HTTP POST events directly to your backend when CIB or EDAHABIA payments complete or fail, secured by cryptographic RSA SHA-256 digital signatures.
Official Payment Event: cib.payment.updated
This notification is automatically delivered via an HTTP POST request in JSON format to the webhook_url specified when creating a CIB or EDAHABIA transaction.
Approved Payment Event
Dispatched when the customer completes payment with a valid OTP code.
json
1{
2 "event": "cib.payment.updated",
3 "payment_status": "success",
4 "transaction_id": "bb979126-4e55-49dd-8ecc-a1d59867d2b0",
5 "cib_transaction_id": "5965287001",
6 "order_id": "satim_order_a1b2c3d4",
7 "order_number": 5965287001,
8 "order_status": 2,
9 "amount": 150000,
10 "currency": "012",
11 "error_code": null,
12 "error_message": null,
13 "action_code": null,
14 "action_code_description": null,
15 "resp_code": "00",
16 "resp_code_desc": "Approved",
17 "message": "https://yourstore.com/api/cib-webhook/success1500005965287001",
18 "signature": "MEQCIFz8v982hfkjdsf983274hfkjsdf98234kjhsdf...=="
19}Declined / Failed Payment Event
Dispatched when card is declined due to insufficient funds, expiration, or invalid OTP.
json
1{
2 "event": "cib.payment.updated",
3 "payment_status": "failed",
4 "transaction_id": "bb979126-4e55-49dd-8ecc-a1d59867d2b0",
5 "cib_transaction_id": "5965287001",
6 "order_id": "satim_order_a1b2c3d4",
7 "order_number": 5965287001,
8 "order_status": 6,
9 "amount": 150000,
10 "currency": "012",
11 "error_code": 5,
12 "error_message": "Transaction declined by issuer",
13 "action_code": 116,
14 "action_code_description": "Insufficient funds",
15 "resp_code": "05",
16 "resp_code_desc": "Declined",
17 "message": "https://yourstore.com/api/cib-webhook/failed1500005965287001",
18 "signature": "MEYCIQDdr7234kjhsdf98234kjhsdf89234kjhsdf...=="
19}Webhook Payload Fields Reference
| Field | Type | Description |
|---|---|---|
| event | string | Official event identifier, always "cib.payment.updated" |
| payment_status | 'success' | 'failed' | Final payment outcome: "success" or "failed" |
| transaction_id | string (UUID) | Unique SofizPay internal transaction UUID |
| cib_transaction_id | string | Official SATIM/CIB banking order identifier |
| order_number | number | Numeric order identifier from the SATIM gateway |
| order_status | number | SATIM numeric status code (2: Approved, 6: Declined, 3: Timeout/Cancelled) |
| amount | number (centimes) | Amount in Algerian centimes (e.g. 150000 = 1,500.00 DZD) |
| currency | string | ISO 4217 numeric currency code ("012" for DZD) |
| resp_code | string | Bank response code ("00" for approved transactions) |
| resp_code_desc | string | Human-readable response code description |
| message | string | Original raw message string verified by the digital signature |
| signature | string (Base64) | Cryptographic RSA SHA-256 digital signature from SofizPay |