Webhooks with the PHP SDK
When a customer pays, IZI Pay sends a notification to the webhook URL you gave during onboarding. The Webhooks class helps you:
- check that the notification really comes from IZI Pay;
- read it into a typed object;
- answer in the exact format IZI Pay expects.
How delivery and retries work is explained in Webhooks. The Webhooks class does not need an IziPayClient or your Client App credentials.
Set up
During onboarding you chose an Access-Key: a secret that IZI Pay sends in the Access-Key header of every notification. Give the same value to the SDK.
PHP
Receive a payment by reference
In plain PHP:
PHP
In Laravel (exclude the route from CSRF protection, because IZI Pay cannot send a CSRF token):
PHP
With any other PSR-7 framework, read the header with $request->getHeaderLine('Access-Key') and the body with (string) $request->getBody().
A reference notification contains:
| Field | Meaning |
|---|---|
id | IZI Pay's ID for this notification. Use it to ignore repeats |
reference | The reference that was paid |
amountPaid | Amount paid, in kwanzas |
paidAt | When the customer paid |
transactionId, systemLogNumber, systemLogId | Transaction identifiers, useful for reconciliation |
terminalType, terminalId, terminalLocation | Where the customer paid, for example an ATM |
nib, bank | The payer's account and bank, when sent |
Receive a QR Code payment
Same steps, on your QR Code webhook URL:
PHP
Answer
| Call | When | IZI Pay then |
|---|---|---|
Webhooks::acknowledge($orderId) | You handled it, or had already handled it before | Stops sending it |
Webhooks::acknowledge($orderId, 'Payment already processed') | Same, with your own note | Stops sending it |
Webhooks::reject($orderId, 'Database unavailable') | You could not handle it now | Sends it again later |
The first argument is required: your own ID for the order or payment. The note is optional for acknowledge and required for reject. Both return the JSON text to send back; answer reject with an HTTP 5xx status.
Always answer acknowledge for a repeat you already handled. Answering an error makes IZI Pay keep resending it.
Other checks
$webhooks->ensureAuthentic($header)does the same asisAuthenticbut throwsWebhookExceptionwhen the key is wrong.parseReferencePaymentandparseQrCodePaymentthrowIziPay\Webhooks\WebhookExceptionwhen the body is empty or is not a valid notification. Answer HTTP 400 in that case.- The key is compared in a way that takes the same time whether it is right or wrong, so it cannot be guessed by measuring answers.