Payments
Peach Payments Shopify integration for South African stores.
Peach Payments leans enterprise — it is the gateway behind a large slice of South African mid-market and corporate ecommerce, with a product stack built on the old Oppwa/ACI engine. That heritage means more knobs (multiple channels, risk rules, recurring, tokenisation) and slightly more paperwork than a Yoco or Ozow signup. Peach ships a native Shopify app, so the integration path is much cleaner than the Manual Payment Method dance Payfast and Yoco require. This guide covers both the drop-in COPYandPAY widget and the Hosted Payment Page (HPP) redirect, plus webhook validation.
Prerequisites
- Peach Payments merchant account — FICA, CIPC and risk assessment complete (allow up to 10 business days for enterprise onboarding)
- Entity Id and Access Token from your Peach dashboard (separate test and live credentials)
- Shopify store on any plan — Peach's Shopify app works on Basic upwards
- HTTPS webhook endpoint for payment notifications
- 3DS2 channel enabled on your Peach profile (standard on new accounts)
Step 1. Complete Peach onboarding and risk assessment
Peach has a more thorough intake than most SA gateways — expect CIPC docs, director IDs, bank confirmation, product category questionnaire and sometimes a site review. High-risk categories (supplements, CBD, adult, nutraceutical) may be declined or routed through a specific channel.
Step 2. Install the Peach Payments Shopify app
For most stores, the fastest path is the official Peach Shopify app. Install from the Shopify App Store, connect with your Entity Id and Access Token, and Peach appears as a native payment option at checkout — no Manual Payment Method required.
Step 3. Decide between COPYandPAY widget and HPP redirect
COPYandPAY is a JavaScript widget you embed on your own page — the card form renders inline (via an iframe) so the branding is yours but Peach still receives the PAN directly, keeping you PCI SAQ A. HPP is a full redirect to a Peach-hosted page. For Shopify use the app default (typically HPP); for custom Hydrogen or headless builds, COPYandPAY is worth the effort.
Step 4. Prepare a checkout on the server
For either integration, you first POST to /v1/checkouts to create a checkout session. The response gives you an id used by the widget or HPP URL.
export async function preparePeachCheckout(order: {
id: string;
amountRands: number;
}) {
const body = new URLSearchParams({
entityId: process.env.PEACH_ENTITY_ID!,
amount: order.amountRands.toFixed(2),
currency: 'ZAR',
paymentType: 'DB', // debit / authorize+capture
merchantTransactionId: order.id,
});
const res = await fetch('https://eu-prod.oppwa.com/v1/checkouts', {
method: 'POST',
headers: {
authorization: `Bearer ${process.env.PEACH_ACCESS_TOKEN}`,
'content-type': 'application/x-www-form-urlencoded',
},
body,
});
return res.json(); // { id: "checkout-id", ... }
}Step 5. Render the COPYandPAY widget on your page
Include the Peach script with the checkout id, then the form renders itself. The form submission is captured by Peach — your job is just to render it.
<script src="https://eu-prod.oppwa.com/v1/paymentWidgets.js?checkoutId=CHECKOUT_ID_HERE"></script>
<form
action="https://yourstore.co.za/peach/return?order=SHOPIFY-1001"
class="paymentWidgets"
data-brands="VISA MASTER AMEX"
></form>Step 6. Verify the payment on return
After the widget/HPP completes, the user lands on your return URL. You GET /v1/checkouts/{id}/payment with your Access Token to confirm the final status — never trust a query parameter alone.
export async function verifyPeachPayment(checkoutId: string) {
const url = `https://eu-prod.oppwa.com/v1/checkouts/${checkoutId}/payment?entityId=${process.env.PEACH_ENTITY_ID}`;
const res = await fetch(url, {
headers: { authorization: `Bearer ${process.env.PEACH_ACCESS_TOKEN}` },
});
const data = await res.json();
// Success result codes match /^(000\.000\.|000\.100\.1|000\.[36])/
const success = /^(000\.000\.|000\.100\.1|000\.[36])/.test(
data.result?.code ?? '',
);
return { success, data };
}Step 7. Validate incoming webhooks
Peach webhooks are encrypted — you decrypt with the key from your dashboard (AES-GCM). Check current docs for the exact header names; Peach iterates on signature format. The result code regex in the decrypted payload is what you match against.
Step 8. Enable 3DS2 and test in sandbox
Point your integration at eu-test.oppwa.com with test credentials. Peach publishes 3DS test cards for frictionless, challenge and failure flows — run all three. Also test a declined card and a timeout.
Step 9. Go live and monitor decline rates
Swap entityId and accessToken to live, point at eu-prod.oppwa.com, and watch your authorization rate for the first week. Peach exposes BIN filtering and Fraud Sight — engage them only once you have baseline decline data.
SA gotchas
- Shopify checkout.liquid customisation is Plus-only. On non-Plus plans you accept the checkout as Peach renders it through the app.
- Card fees are plan-dependent (approximately 2.5%–3.4% depending on volume and category — verify your contract). Enterprise pricing is negotiated.
- BIN filtering and Fraud Sight are add-ons — they cost extra and are typically only on Plus/Enterprise plans.
- The test domain (eu-test.oppwa.com) and live domain (eu-prod.oppwa.com) swap needs more than just credential change — you must retest every result code path.
- Peach tokenisation for recurring is a separate capability on your profile. Enabling it after launch requires another risk review.
- Result codes are not booleans — they are structured regex patterns. Copy the official regex into your code, do not write your own success check.
Frequently asked questions
Is Peach POPIA- and PCI-compliant for my Shopify store?
Peach is PCI-DSS Level 1 and their HPP/COPYandPAY flows keep you on PCI SAQ A — the simplest compliance tier. For POPIA, document the third-party processing relationship in your privacy notice and operator agreement.
Does Peach support recurring billing for subscriptions?
Yes via tokenisation plus scheduled server-side charges. Shopify Subscriptions natively supports only Shopify Payments, so for Peach-backed subscriptions on Shopify you need a third-party subscription app that plugs into Peach tokens.
Is 3DS2 mandatory?
Yes — since the 2021 SA Visa/Mastercard mandate. Peach handles the challenge flow on their hosted page. A small drop-off on the challenge step is expected.
Can I use Peach on a Shopify Basic plan?
Yes, the Peach Payments Shopify app works on all Shopify plans. You only need Plus if you want to deeply customise the checkout experience around it.
How long does settlement take?
T+1 to T+2 business days for card for established merchants. New accounts may have a rolling reserve for the first 90 days.