Redeem Vouchers by Pin

With Scan to Pay vouchers recipients receive the vouchers in their Scan to Pay app or Scan to Pay White Label app if applicable, and the vouchers can be used at any of the 600,000 Scan to Pay merchant locations in South Africa. Scanning a QR from the Scan to Pay application is the default redemption mechanism for vouchers. Any existing Scan to Pay merchant can automatically redeem vouchers using their existing integration and customer payment journey.

Scan to Pay vouchers also supports redemption by pin. This can be seen as a more familar voucher journey where users are given a pin that can then be used at supporting merchants to redeem the voucher. By default Scan to Pay vouchers are allocated a 16 digit pin when they are created. Merchants that want to redeem vouchers by pin can do so by using the ZA_QRCODE payments use case. The only difference is that the source store of value is specified by a voucher pin.

Retrieving voucher pins

Voucher pins can be shown in the Scan to Pay app when viewing a voucher:

Alternatively if using APIs the voucherPin will be returned in the response when provisioning vouchers by API and also when using the GET wallets endpoints.

📘

Note

To view a voucher pin by API the calling user must have the Wallet.VoucherPin.WalletType.READ.Allowed permission.

Prerequisites

• A valid JWT
• Voucher pin entered by the customer

Example request to redeem a voucher by pin:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/payments
{
  "additionalFields": [
    {
      "id": "voucherPin",
      "value": "7064872048864338"
    }
  ],
  "amount": 124,
  "description": "Voucher Payment",
  "externalUniqueId": "9d120960-b4a7-4bff-9b3b-a351b4eb534548471-005",
  "paymentData": "1146471424",
  "reference": "9d1sasasa20960-b4a7-4bff-9b3b-a35415be5b6415487",
  "type": "ZA_QRCODE",
   "currency": "ZAR"
}

Example response:

{
  "paymentId": 680711,
  "externalUniqueId": "9d120960-b4a7-4bff-9b3b-a351b4eb534548471-005",
  "status": "SUCCESSFUL",
  "amount": 124,
  "description": "Voucher through Payment",
  "merchantName": "STPVoucher",
  "currency": "ZAR",
  "additionalFields": [
    {
      "id": "VoucherPin",
      "value": "7064872048864338"
    }
  ],
  "acceptedCardSchemes": [],
  "acceptedPaymentMechanisms": [
    "WALLET"
  ],
  "paymentType": "WALLET",
  "created": "2024-06-19T08:26:40.000Z",
  "paymentInstrumentInfo": {},
  "fee": 0,
  "paymentReference": "9d1sasasa20960-b4a7-4bff-9b3b-a35415be5b6415487",
  "walletId": 2502934,
  "customerId": 194446,
  "organisationId": 93149,
  "gatewayTransactionId": "Payment-680711",
  "paymentTerminalData": {}
}