Vouchers

Last updated: 2026-05-22

Use this page when the selected H2H mobile-money pay-in route requires a voucher PIN. It supplements the standard create pay-in request with voucher-specific mobile-money details.

When to use vouchers

Voucher PINs apply only to voucher-based H2H mobile-money pay-ins. Start with GET /merchant/api/v1/catalog, then call GET /merchant/api/v1/payins/mmo for the selected market and request context.

If the selected market/operator requires voucher collection, send the voucher PIN in mobileMoneyDetails.voucherPin when creating the pay-in. When discovery returns an operator for the voucher route, send that value exactly as returned.

Voucher request fields

Use POST /merchant/api/v1/payins/create with paymentMethod = "PAYMENT_METHOD_MOBILE_MONEY".

Send the standard H2H create pay-in fields from Endpoints, including amount, currencyCode, countryCode, merchantReference, and redirectUrl, plus the mobile-money detail fields below.

Field	Required	Notes
mobileMoneyDetails.mobileNumber	Yes	Customer wallet number / MSISDN
mobileMoneyDetails.operator	Conditional	Operator returned by GET /merchant/api/v1/payins/mmo when the voucher route is operator-aware
mobileMoneyDetails.voucherPin	Yes for voucher routes	Voucher PIN for voucher-based mobile-money pay-in routes

Treat voucherPin as sensitive customer input. Send it only for voucher-based routes and only over server-side secret-key requests.

Example

curl -X POST "https://merchants-api.example.com/merchant/api/v1/payins/create" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10000",
    "currencyCode": "BWP",
    "countryCode": "BW",
    "paymentMethod": "PAYMENT_METHOD_MOBILE_MONEY",
    "merchantReference": "VCH-1001",
    "redirectUrl": "https://merchant.example/return",
    "trafficVertical": "TRAFFIC_VERTICAL_OTHER",
    "customerSegment": "CUSTOMER_SEGMENT_FTD",
    "mobileMoneyDetails": {
      "mobileNumber": "26772345684",
      "operator": "BWVCH",
      "voucherPin": "1234567890123456"
    }
  }'

Track the latest accepted outcome through webhooks and GET /merchant/api/v1/payment/{id}. Redirect returns and provider instructions are not payment-success signals.