Gateways
Yoco
South African card, Apple Pay/Google Pay and instant EFT payments via Yoco hosted checkout.
On this page
South African card, Apple Pay/Google Pay and instant EFT payments via Yoco hosted checkout.
At a glance#
| Type | yoco |
| Countries | South Africa |
| Currencies | ZAR |
| Capabilities | Hosted checkoutOn-demand status verification |
| Gateway docs | developer.yoco.com/docs/checkout-api/introduction |
Checkout experience#
Redirect to Yoco hosted checkout (redirectUrl from POST /api/checkouts).
Configuration fields#
Enter these in the dashboard under Settings → Payment providers → Yoco. Secret fields are encrypted at rest and masked after saving; leave a secret blank when editing to keep the stored value.
| Field | Type | Notes |
|---|---|---|
| Live secret key liveSecretKey | Secret | Yoco Business Portal > Selling Online > Payment Gateway. Used when Sandbox is off. |
| Test secret key testSecretKey | Secret | Used when Sandbox is on. |
| Webhook signing secretrequired webhookSecret | Secret | Returned by POST https://payments.yoco.com/api/webhooks when you register this provider's webhook URL (one per key/mode). |
Every provider also has Enabled, Sandbox / test mode and Default checkout method switches.
Notification URL#
https://app.centrapoint.co.za/api/webhooks/yoco?provider={providerId}Copy the exact URL, with your provider ID filled in, from Settings → Payment providers.
- Register this provider's notification URL once with Yoco (POST https://payments.yoco.com/api/webhooks). Yoco returns a whsec_ secret; paste it into the provider's webhook secret field.
- One webhook registration is needed per key and mode (test/live).
How notifications are verified#
- Standard Webhooks signature: HMAC-SHA256 over "webhook-id.webhook-timestamp.body", keyed with the base64 secret after whsec_, checked against the webhook-signature header.
- Only payment.succeeded and payment.failed events are processed; a test-mode event sent to a live provider (or vice versa) is rejected.
- Where possible the checkout is re-fetched from Yoco to confirm the reference and status before it is applied.
- The amount and currency must match the transaction before it can be marked complete.
Going live#
- Test with sandbox credentials and Sandbox / test mode on, and confirm the notification appears as processed in the Webhook log.
- Replace the credentials with live ones and switch off Sandbox / test mode.
- Update any URL or secret configured in the gateway's portal for the live environment.
- Make a small live payment and confirm it with the Transactions API.