Integration Guide

Server-to-Server Integration Guide

Direct backend API integration for merchants who need full control over the payment journey and custom checkout experiences.

Available in Sandbox
15 min read UAT sample examples included

PCI DSS compliance required

Server-to-Server integration typically requires you to collect or handle card data directly. You must be PCI-DSS compliant. If you cannot meet these obligations, use Copy n Pay instead.

Overview

Server-to-Server integration gives your backend direct control over payment initiation, authorisation, capture and post-payment operations.

Your application collects or transmits payment data to the gateway via server-side HTTP POST requests. This offers maximum flexibility but places greater security and compliance responsibility on the merchant.

Use Server-to-Server when you operate a custom checkout, mobile app backend or enterprise payment orchestration layer — and only when your organisation understands the PCI implications.

Typical merchant profile
Enterprises, payment aggregators, custom checkout builders and development teams with PCI-capable infrastructure and security governance.

Best Use Cases

  • Custom checkout UI with backend-controlled payment orchestration
  • Synchronous card payments where the result is needed in near real-time
  • Asynchronous flows requiring shopper redirect for 3-D Secure or issuer validation
  • Pre-authorisation followed by capture for hospitality, events or reservations
  • Back-office refund, reversal and chargeback reflection where enabled by acquirer

How the Flow Works

1

Collect or prepare payment data

Your system gathers payment details according to your PCI scope. Card data must only be handled if you are compliant.

2

Initiate payment (server POST)

Send a server-to-server POST with entity ID, amount, currency, payment type and card or payment method data. For async flows include a URL-encoded shopperResultUrl.

3

Handle immediate or redirect response

Synchronous flows return a payment ID directly. Asynchronous flows may return redirect parameters (url, method, parameters) for shopper validation.

4

Verify payment status

For async flows the shopper returns to shopperResultUrl with resourcePath (/v1/payments/{id}). Perform a server-side GET to confirm outcome.

5

Capture or manage (optional)

For PA (pre-authorisation) flows, send a capture (CP) request. Use back-office operations for refunds (RF) where enabled.

Technical Implementation Steps

  1. Confirm PCI DSS obligations with your security team and acquiring bank before collecting card data.
  2. Obtain entity ID and bearer access token for UAT and production channels.
  3. Choose transaction flow: debit (DB), pre-authorisation + capture (PA → CP), or async variants.
  4. Implement server-side POST to the payments endpoint — all parameters in the request body.
  5. Store the returned payment ID for all subsequent status and back-office calls.
  6. For async payments, render redirect HTML form from gateway response parameters.
  7. Verify final status before fulfilment; do not trust client-side state alone.
  8. Implement back-office refund/reversal only where acquirer has enabled the capability.

Required Configuration

PCI DSS compliance Required if collecting card data — consider Copy n Pay to reduce scope.
Merchant enablement Required — subject to acquiring bank and Zimswitch approval.
Payment types DB (debit), PA (pre-auth), CP (capture), RF (refund) — availability subject to connector.
shopperResultUrl Required for asynchronous flows — must be HTTPS and URL-encoded in requests.
Authentication Bearer access token + entityId on every request.
Back-office APIs Refund, rebill, chargeback operations — requires enablement; to be confirmed with acquirer.

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.

Debit payment (DB)

curl -X POST '{{BASE_URL}}/v1/payments' \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ -d 'entityId={{ENTITY_ID}}' \ -d 'amount={{AMOUNT}}' \ -d 'currency={{CURRENCY}}' \ -d 'paymentType=DB' \ -d 'paymentBrand={{PAYMENT_BRAND}}' \ -d 'card.number={{CARD_NUMBER}}' \ -d 'card.holder={{CARD_HOLDER}}' \ -d 'card.expiryMonth={{EXPIRY_MONTH}}' \ -d 'card.expiryYear={{EXPIRY_YEAR}}' \ -d 'card.cvv={{CVV}}'

Pre-authorisation (PA)

curl -X POST '{{BASE_URL}}/v1/payments' \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ -d 'entityId={{ENTITY_ID}}' \ -d 'amount={{AMOUNT}}' \ -d 'currency={{CURRENCY}}' \ -d 'paymentType=PA' \ ... card fields ...

Capture (CP)

curl -X POST '{{BASE_URL}}/v1/payments/{{PAYMENT_ID}}' \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ -d 'entityId={{ENTITY_ID}}' \ -d 'amount={{AMOUNT}}' \ -d 'currency={{CURRENCY}}' \ -d 'paymentType=CP'
  • HTTP POST parameters must be in the message body, not the URL.
  • Successful payment responses include an id — store it for capture, refund and status queries.
  • Async flows return redirect JSON (url, method, parameters) to guide the shopper through issuer validation.
  • resourcePath on callback is typically /v1/payments/{id}.
  • Status GET requests are limited to two per minute per transaction; query endpoints may offer alternatives — confirm with Zimswitch.
  • Not all payment brands support every flow (PA, DB, async) — verify with your acquirer.
  • Back-office refund (RF), rebill (RB), chargeback (CB) and chargeback reversal (CR) depend on connector enablement.

Response and Status Handling

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

Success

Payment authorised or captured per your payment type. Verify result codes and acquirer rsp_code before fulfilment.

Declined

Issuer or gateway declined the transaction. Return a clear message; do not expose raw gateway errors to shoppers.

Pending / Redirect required

Async flow needs shopper action. Redirect using gateway-supplied parameters and verify on return.

Pre-authorised

Funds reserved (PA). Capture (CP) before settlement window expires — timing subject to acquirer rules.

Security and Compliance Notes

  • PCI-DSS compliance is mandatory if you collect, process or transmit card data on your systems.
  • Zimswitch documentation recommends Copy n Pay where merchants want to minimise PCI scope.
  • Never log or persist full PAN, CVV or magnetic-stripe data.
  • Use TLS 1.2+ for all API communication; pin production endpoints after confirmation with Zimswitch.
  • Restrict access tokens to backend services with secrets management.
  • Validate amount, currency and merchant transaction ID on every status response.
  • Implement idempotent fulfilment to handle duplicate callbacks or retries.

Testing Checklist

  • Confirm PCI and security sign-off before UAT card testing.
  • Test synchronous debit (DB) with UAT test card in sandbox.
  • Test pre-authorisation (PA) and capture (CP) if your use case requires it.
  • Test async flow with shopperResultUrl and resourcePath verification.
  • Test declined payment handling without application errors.
  • Verify payment ID storage and reconciliation against merchant transaction ID.
  • Test refund (RF) in sandbox only if enabled — otherwise mark as pending acquirer enablement.
  • Confirm no card data appears in application logs.

Go-Live Checklist

  • PCI attestation or SAQ completed as applicable to your integration pattern.
  • Production credentials provisioned and stored in secrets manager.
  • Production {{BASE_URL}} confirmed with Zimswitch — do not assume UAT hostnames.
  • Async shopperResultUrl and any notification URLs use valid HTTPS certificates.
  • Capture and refund workflows tested against acquirer settlement rules.
  • Monitoring and alerting on payment failures configured.
  • Acquiring bank certification or sign-off obtained.

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

Server-to-Server gives full backend control over payments and post-payment operations.

It requires stronger PCI and security governance than hosted checkout.

Supports debit, pre-auth/capture and async flows depending on brand and acquirer.

Always verify payment status server-side before delivering goods or services.

Enable refunds and advanced operations only where your bank has provisioned them.

Test in Sandbox Start Onboarding All Integrations

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