Integration Guide

Pay by Link Integration Guide

Generate shareable payment links for invoices, campaigns, events and customer-not-present collections.

Requires Enablement
10 min read UAT sample examples included

Enablement required

Pay by Link may not be active on all merchant channels. Confirm availability with your acquiring bank or Zimswitch before go-live.

Overview

Pay by Link lets you create a secure payment link that customers open to complete payment on a hosted payment page.

The link can be shared by email, chat, SMS, QR code or social channels — ideal when there is no full e-commerce checkout or when payment is initiated after a conversation.

The customer experience uses a branded hosted page (logo, colours configurable) across devices. Your backend creates the link; your systems must track references and verify payment results.

Typical merchant profile
Charities, campaign managers, event organisers, invoice-based merchants, call centres and social-commerce sellers who need simple payment collection without a website checkout.

Best Use Cases

  • Charity campaign links shared on WhatsApp, email or social media
  • Event registration or ticket payment links sent after booking
  • Invoice and statement payments for professional services
  • Call-centre agents generating one-off payment links during support calls
  • In-store QR code payments where createQRCode is enabled

How the Flow Works

1

Generate payment link (server)

Your backend sends a server-to-server POST with order type, amount, currency and optional branding. The gateway returns a link URL (and optionally a QR code).

2

Distribute link to customer

Share the link via email, SMS, chat or display a QR code. SMS distribution is optional and may incur additional costs.

3

Customer pays on hosted page

The customer opens the link, reviews amount and merchant branding, and completes payment on the secure hosted page.

4

Redirect and verify status

After payment the customer is redirected to your shopperResultUrl with id and checkoutId parameters. Verify payment via GET to the returned resourcePath.

5

Optional link management

Check link status, SMS delivery status, or deactivate the link when no longer needed.

Technical Implementation Steps

  1. Request Pay by Link enablement from your acquiring bank or Zimswitch.
  2. Implement server-side POST to create the payment link with amount, currency and merchant reference.
  3. Extract the link from the response and store the payment link id for status queries.
  4. Distribute the link through your chosen channel (email API, manual copy, QR display).
  5. Configure shopperResultUrl for post-payment redirect.
  6. On callback, GET baseUrl + resourcePath to confirm payment before marking invoice or order as paid.
  7. Optionally poll link status or deactivate links when expired or paid.

Required Configuration

Enablement Requires Zimswitch / acquiring bank approval — not assumed live for all merchants.
Link validity validUntil + validUntilUnit (HOUR or DAY); default 90 days if not specified.
Branding layout.logo, colours and template options — see Pay by Link API reference.
QR code Set createQRCode=true to receive qrCode in response — useful for in-person sharing.
SMS distribution Optional platform feature; disabled in sandbox by default; additional costs apply.
shopperResultUrl HTTPS redirect target after customer completes payment.

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.

Create payment link

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}}' \ -d 'shopperResultUrl={{SHOPPER_RESULT_URL}}'

Verify payment status

curl -G '{{BASE_URL}}{{RESOURCE_PATH}}' \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ -d 'entityId={{ENTITY_ID}}' # Example resourcePath after redirect: # paybylink/v1/{id}/checkouts/{checkoutId}/payment

Payment link status

curl -G '{{BASE_URL}}/paybylink/v1/{{LINK_ID}}' \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ -d 'entityId={{ENTITY_ID}}'
  • Link creation is a server-to-server POST — parameters in body, not URL.
  • Response includes a link URL to share with the customer.
  • After payment, shopperResultUrl receives id (payment page id) and checkoutId (checkout session id).
  • Payment status resourcePath format: paybylink/v1/{id}/checkouts/{checkoutId}/payment.
  • Link status: GET /paybylink/v1/{id}.
  • Deactivate link: HTTP DELETE /paybylink/v1/{id}.
  • SMS status (if used): GET /paybylink/v1/{id}/sms/status — sandbox SMS is disabled by default.
  • Exact create endpoint path to be confirmed during merchant enablement with Zimswitch.

Response and Status Handling

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

Link created

Link is active and can be shared until expiry or deactivation.

Payment successful

Verified via server-side GET — mark invoice/order as paid.

Payment failed / declined

Customer may retry if link is still valid; communicate clearly.

Link expired or deactivated

Generate a new link for the customer.

Security and Compliance Notes

  • Create links only from your backend — never expose access tokens in shareable client code.
  • Treat payment links as sensitive URLs; avoid posting publicly without amount/context controls.
  • Use HTTPS for shopperResultUrl and any terms/privacy URLs configured on the page.
  • Verify payment server-side before releasing goods, tickets or donation receipts.
  • Do not include card data in link creation requests unless operating under appropriate PCI controls.
  • Log link IDs and merchant references — not customer card details.

Testing Checklist

  • Confirm Pay by Link is enabled for your UAT channel.
  • Create a test link for a small amount and open it in a browser.
  • Complete payment with UAT test card and confirm redirect to shopperResultUrl.
  • Verify payment status via resourcePath GET before marking test order paid.
  • Test link status endpoint with returned link id.
  • Test link deactivation if your workflow requires it.
  • If using QR codes, verify createQRCode response renders correctly.
  • SMS testing requires production enablement — do not assume sandbox SMS works.

Go-Live Checklist

  • Pay by Link feature enabled on production channel.
  • Branding (logo, colours) approved by marketing/compliance.
  • Link expiry policy defined (validUntil / validUntilUnit).
  • Reconciliation process maps link id and merchantTransactionId to orders.
  • HTTPS shopperResultUrl in production.
  • Customer support trained on resending links and handling expired links.
  • SMS costs and enablement confirmed with account manager if using SMS distribution.

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.

Summary

Pay by Link is ideal for customer-not-present payments without a full checkout.

Your server creates a link; the customer pays on a secure hosted page.

Share via email, chat, QR or SMS (where enabled).

Always verify payment status before fulfilment.

Requires enablement and clear link expiry and reconciliation practices.

Test in Sandbox Start Onboarding All Integrations

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