Merchant Redemption

Merchant redemption is the process for validating vouchers, creating redemption claims, completing OTP verification, and applying the final external redemption callback. Merchant operators can use the portal, while server-to-server integrations use the merchant-redeem API under /api/v1/merchant/client.

Scope

Gift vouchers represent prepaid digital value that can be redeemed at eligible merchants. The merchant portal manages voucher lookup, balance and restriction checks, claim creation, and final verification.

Key Capabilities

• Log in with a merchant API key and use the returned x-api-token.
• Validate voucher code, balance, status, and expiry.
• Confirm whether a voucher is restricted to the current merchant.
• Create a redemption claim for the selected amount.
• Verify the claim with the OTP provided by the voucher owner.
• Complete external redemption through a callback.

Merchant-Redeem API Surface

Method	Path	Purpose
POST	/api/v1/merchant/client/auth/login	Exchange merchant API key for accessToken.
GET	/api/v1/merchant/client/topup-transactions/:voucherCode	Look up voucher status, balance, and service fee.
POST	/api/v1/merchant/client/topup-transactions/initiate-claim	Create a claim and send OTP to the voucher owner.
POST	/api/v1/merchant/client/topup-transactions/redeem-gift	Submit OTP and prepare external redemption.
POST	/api/v1/merchant/redeem-gift/callback	Complete the pending external redemption.

Redemption Flow

Operator Guidance

The portal handles session authentication and authorization. Operators confirm voucher details, enter the redemption amount, and complete OTP verification.

Merchant-Redeem Authentication

For server-to-server redemption, merchant-redeem requests must include:

• x-api-token from merchant-redeem login
• x-signature on signed POST requests

Merchant-redeem idempotency uses the optional request-body idempotencyKey, not the Idempotency-Key header.

Next Steps

• Getting Started
• Voucher Redemption
• Idempotency