Peach Payments
This page provides an overview of the payments methods provided by the Peach Payments adapter in the IXOPAY platform. It also includes a full list of all configuration options available to you when integrating Peach Payments within your payments landscape, as well as an overview of the parameters required when submitting a transaction via IXOPAY's API.
Peach Payments is a payment service provider for Africa, built on the OPPWA platform. The Peach connector processes redirect-based alternative payment methods via Peach's hosted Checkout (v2) page for South Africa and Mauritius.
Supported features
Payment methods
The table below lists the payment methods that Peach Payments supports. It also includes the available processing options and the supported transaction types for each of those payment methods.
| Payment method | Processing options | Transaction types | |
|---|---|---|---|
PayShap (PayShap) | Hosted payment pages Full-page redirect | Debit | Currencies: ZAR Countries: ZA |
MCB Juice (MCBJuice) | Hosted payment pages Full-page redirect | Debit | Currencies: MUR Countries: MU |
Blink by Emtel (BlinkByEmtel) | Hosted payment pages Full-page redirect | Debit | Currencies: MUR Countries: MU |
Currencies
Peach Payments supports the following currencies: ZAR, MUR.
Mapping to Peach Payments
Parameters
Request mapping
| Gateway parameter | Peach Payments parameter | Type | Description |
|---|---|---|---|
amount | amount | required number | Transaction amount (major units, two decimals) |
currency | currency | required string | ISO 4217 currency code |
successUrl | shopperResultUrl | required string | Shopper return URL after completing the payment |
cancelUrl | cancelUrl | optional string | Shopper return URL after cancelling the payment |
customer.identification | customer.merchantCustomerId | optional string | Merchant-side customer identifier |
customer.firstName | customer.givenName | optional string | Customer first name |
customer.lastName | customer.surname | optional string | Customer last name |
customer.billingPhone | customer.mobile | optional string | Customer mobile number |
customer.email | customer.email | optional string | Customer email address |
customer.nationalId | customer.idNumber | optional string | Customer national ID number |
customer.billingAddress1 … | billing.street1 … | optional string | Billing address fields |
customer.shippingAddress1 … | shipping.street1 … | optional string | Shipping address fields |
Response mapping
| Gateway parameter | Peach Payments parameter | Type | Description |
|---|---|---|---|
purchaseId (adapter transaction id) | id | string | Peach payment unique id (from the status response) |
| second adapter transaction id | checkoutId | string | Peach checkout session id |
Error codes
| Gateway error code | Peach Payments error code | Peach Payments error message |
|---|---|---|
1002 (invalid request data) | HTTP 400 / 404 | Invalid request body / Channel not found |
1007 (invalid configuration) | HTTP 401 | Access denied. |
2003 (transaction declined) | 800.100.* and others | Transaction declined |
2002 (user cancelled) | 100.396.101 | Cancelled by user |
1003 (processing error) | HTTP 5xx, 900.* | Temporary failure at Peach |
Webhooks
The connector consumes Peach's webhooks, so a payment reaches a final state even when the shopper never returns from their banking app. Peach delivers on two channels, both arriving on the same webhook URL and both supported:
- Encrypted OPPWA webhooks ("new style"): the payload is AES-256-GCM encrypted; the connector's Webhook Secret is the hex decryption key from the Peach dashboard. These are always decrypted and authenticated — the Webhook signing setting below does not apply to this channel.
- Checkout webhooks: a plaintext payload authenticated by HMAC-SHA256 signature headers
(
x-webhook-*). The Webhook Secret is the HMAC key exactly as shown in the Peach dashboard — it looks base64-encoded but must be entered verbatim, never decoded.
Setup:
- Register the connector's generic postback URL in the Peach Payments Dashboard (Webhooks):
https://<gateway-host>/postback/<connectorGuid>. Peach accepts one webhook URL per account. - Enter the secret from the Peach dashboard into the connector's Webhook Secret field.
- Dashboard settings: Types = PAYMENTS; the "Wrapper" setting may be left at either value (both the bare and the JSON-wrapped body form are accepted). Newly created webhooks are inactive until tested and activated in the dashboard.
- Only
DB(debit) webhooks change transaction state. Refund/reversal webhooks (RF/RV) are acknowledged but not processed until refunds are implemented (CONN-2329); REGISTRATION, SCHEDULE and RISK notifications are acknowledged and ignored.
Webhook signing
The Webhook signing connector option controls signature verification on the Checkout webhook channel:
- Enabled (the default, also used when the option is not set): the
x-webhook-*HMAC signature headers are verified against the Webhook Secret; unsigned or invalidly signed deliveries are rejected. Requires webhook signing to be enabled in the Peach dashboard, and a webhook secret to be configured on the connector — transactions fail fast with a configuration error if the secret is missing. - Disabled: Checkout webhooks are accepted without any authentication (Peach accounts that never enabled signing in the dashboard send no signature headers at all). Only set this if signing genuinely cannot be enabled at Peach — with verification disabled, anyone who knows the postback URL can submit forged status notifications. Encrypted OPPWA webhooks remain authenticated regardless of this setting.
Miscellaneous
- The connector completes transactions via the Peach Checkout status call when the shopper returns, via webhooks (see above), plus a server-side status poll as a last-resort fallback for shoppers who never return.
- The domain initiating the checkout must be added to the allowlist in the Peach Payments Dashboard; it is configured on the connector ("Whitelisted domain").