Integration Guide

Copy n Pay Integration Guide

Hosted payment widget integration for merchants who want SAQ-A friendly checkout with minimal PCI scope.

Live
12 min read UAT sample examples included

Overview

Copy n Pay (COPYandPAY) is a hosted payment widget approach. Your server prepares a checkout session, your website renders the secure payment form, and the shopper enters card details inside gateway-hosted fields rather than on your own systems.

This reduces PCI exposure because sensitive card data is captured through the payment widget and processed by the approved payment gateway — not stored on your merchant application.

Copy n Pay suits websites, donation pages, campaign checkouts, bill-pay portals and merchants that want a faster path to production without building a fully custom card capture UI.

Typical merchant profile
E-commerce merchants, charities, event organisers and SMEs with a web checkout who prefer hosted card entry and server-side result verification.

Best Use Cases

  • Online store checkout where you control the cart but want hosted card entry
  • Charity and campaign donation pages on Zimswitch Online
  • Bill payment and token purchase flows with redirect-style completion
  • Merchants prioritising lower PCI scope (SAQ-A style hosted fields)
  • Rapid UAT prototyping before deeper customisation

How the Flow Works

1

Prepare checkout (server)

Your backend sends a server-to-server POST to create a checkout with amount, currency, payment type and merchant transaction reference. The gateway returns a checkout ID.

2

Render payment widget (browser)

Load the payment widget script using the checkout ID and display a payment form on your checkout page. The shopper enters card details in hosted fields.

3

Shopper submits payment

The shopper completes authentication (including 3-D Secure where required) and submits payment through the widget.

4

Redirect to result URL

After processing, the shopper is redirected to your shopperResultUrl with a resourcePath query parameter.

5

Verify payment status (server)

Your server performs a GET to baseUrl + resourcePath using your entity ID and access token. Only treat the order as paid after a successful verified response.

Technical Implementation Steps

  1. Obtain UAT credentials (entity ID and bearer access token) from your acquiring bank or Zimswitch.
  2. Implement a server-side POST to {{BASE_URL}}/v1/checkouts — never expose credentials in frontend code.
  3. Store the returned checkout ID and associate it with your merchant transaction reference.
  4. Render the payment widget script and paymentWidgets form on your checkout page.
  5. Configure shopperResultUrl to a secure HTTPS endpoint on your site.
  6. On callback, verify payment status server-side before fulfilling goods, services or donation receipts.
  7. Complete sandbox test cases, then request production enablement.

Required Configuration

Merchant enablement Required — contact your acquiring bank or Zimswitch Innovation Hub.
Environment UAT/sandbox for testing; separate production credentials for go-live.
Entity ID Issued per merchant channel — include in all API requests.
Access token Bearer authorization header — server-side only.
shopperResultUrl HTTPS URL on your site where the shopper returns after payment.
Notification URL To be confirmed during merchant enablement if server-to-server webhooks are provisioned.
Supported brands Configure via data-brands on the payment form — subject to acquirer enablement.

API / Request Guidance

Sample UAT requests use placeholders only. Replace with values issued by your acquiring bank. {{BASE_URL}} must end with a trailing slash when concatenating resource paths.

Prepare checkout (Copy n Pay)

curl -X POST '{{BASE_URL}}/v1/checkouts' \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ -d 'entityId={{ENTITY_ID}}' \ -d 'amount={{AMOUNT}}' \ -d 'currency={{CURRENCY}}' \ -d 'paymentType={{PAYMENT_TYPE}}' \ -d 'merchantTransactionId={{MERCHANT_TRANSACTION_ID}}'

Payment widget (frontend)

<script src="{{BASE_URL}}/v1/paymentWidgets.js?checkoutId={{CHECKOUT_ID}}"></script> <form action="{{SHOPPER_RESULT_URL}}" class="paymentWidgets" data-brands="{{PAYMENT_BRAND}}"></form>

Verify payment status

curl -G '{{BASE_URL}}{{RESOURCE_PATH}}' \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ -d 'entityId={{ENTITY_ID}}'
  • All HTTP POST parameters must be sent in the request body, not the URL query string.
  • A checkout ID can be reused within its lifetime (e.g. page reload) but may produce multiple transaction attempts — always verify the final status.
  • Checkout IDs expire after successful payment or after approximately 30 minutes, whichever comes first.
  • Payment status GET requests are throttled to two per minute per checkout; plan verification accordingly.
  • After a successful status response, the checkout ID cannot be reused — use transaction reporting for later queries.
  • Verify returned amount, currency, brand, type and transaction ID against your order before fulfilment.

Response and Status Handling

Never fulfil goods, services or donation receipts until payment status is verified server-side.

Success

Gateway result codes indicate success and acquirer response is acceptable. Fulfil only after server-side verification.

Declined

Payment rejected by issuer or gateway. Show a friendly message and allow retry with a new checkout if needed.

Pending

Payment may still be processing or awaiting shopper action. Do not fulfil until status is confirmed.

Error

Technical or validation failure. Log safe metadata only and prompt the shopper to retry or contact support.

Security and Compliance Notes

  • Copy n Pay is designed for SAQ-A style hosted card entry — card data is entered in gateway-hosted fields.
  • Never store or log full PAN, CVV or PIN on your systems.
  • Keep entity ID and access token on the server only — never embed in client-side JavaScript.
  • Use HTTPS for all checkout and callback URLs.
  • Always verify payment status server-side; a redirect alone does not confirm payment.
  • Mask any card references in logs; store only gateway transaction IDs and your merchant references.

Testing Checklist

  • Obtain UAT entity ID and access token from your acquiring bank.
  • Create a sandbox checkout for a small test amount (e.g. USD 0.10).
  • Render the payment widget on a test page and complete payment with approved test card data.
  • Confirm shopperResultUrl receives resourcePath on redirect.
  • Verify payment status via server-side GET before showing success to the shopper.
  • Test a deliberate decline and confirm graceful handling.
  • Test page reload/back-button behaviour and confirm you still verify final status.
  • Confirm no credentials appear in browser dev tools or page source.

Go-Live Checklist

  • Production credentials issued and stored securely.
  • Production {{BASE_URL}} configured — to be confirmed with Zimswitch.
  • HTTPS shopperResultUrl deployed and reachable.
  • Payment status verification implemented on server.
  • Error and decline messaging reviewed for customer experience.
  • Acquiring bank / Zimswitch sign-off on test results.
  • Support contact and reconciliation process agreed.

Common Mistakes

Avoid this by following the verification, credential and PCI guidance in the sections above.

Avoid this by following the verification, credential and PCI guidance in the sections above.

Avoid this by following the verification, credential and PCI guidance in the sections above.

Avoid this by following the verification, credential and PCI guidance in the sections above.

Avoid this by following the verification, credential and PCI guidance in the sections above.

Avoid this by following the verification, credential and PCI guidance in the sections above.

Avoid this by following the verification, credential and PCI guidance in the sections above.

Summary

Copy n Pay lets you add secure hosted card checkout with lower PCI burden.

Your server creates a checkout; the widget collects card data safely.

Always verify payment status on your server after redirect.

Ideal for donations, retail checkout and fast merchant go-live.

Production requires bank enablement, HTTPS callbacks and credential protection.

Test in Sandbox Start Onboarding All Integrations

Reference material aligned with Zimswitch developer documentation. Confirm endpoint availability during merchant enablement.