Wallet Codes

Wallet codes are redeemable codes that add credit to a customer's wallet. Use them for promotions, gift cards, referral rewards, refund credits, and goodwill gestures.

What are Wallet Codes?

A wallet code is a unique alphanumeric string that a customer redeems to receive wallet credit. Codes can be restricted to specific customers or available to anyone.

Code Types

Creating Codes

From the Dashboard

1. Go to Product > Wallet Codes
2. Click Create Code
3. Configure:
   • Amount — Credit value in your currency
   • Code type — Select from the types above
   • Code — Auto-generated (RK-XXXX-XXXX format) or enter a custom code
   • Customer restriction — Any customer, or a specific customer
   • Expiry date — Optional; code becomes invalid after this date
   • Description — Internal note
4. Click Create

Via the API

POST /v2/wallet-codes

{
  "amountCents": 2500,
  "currency": "GBP",
  "codeType": "promotional",
  "customCode": "SUMMER2026",
  "customerId": null,
  "expiresAt": "2026-09-01T00:00:00Z",
  "description": "Summer promotion"
}

Code Format

• Auto-generated: RK-XXXX-XXXX (uppercase alphanumeric, 8 characters after prefix)
• Custom: Any string up to 50 characters (automatically uppercased, spaces removed)

Custom codes are validated for uniqueness within the merchant's account.

Customer Restrictions

When a code is restricted to a specific customer, other customers see an "Invalid code" error.

Expiry and Auto-Expiry

• Set an optional expiry date when creating a code
• A daily cron job marks expired codes as expired
• Expired codes cannot be redeemed
• Already-redeemed credits are not affected by code expiry (lot expiry is separate)

Redemption Flow

Customer Portal

1. Customer logs into the Customer Portal
2. Clicks Redeem a Code on their wallet balance card
3. Enters the code
4. Credit is added instantly to their wallet

At Checkout

1. Customer sees "Have a code?" input on the checkout page
2. Enters the code
3. Credit is applied to the invoice total
4. Remaining balance (if any) stays in the wallet

Via API

POST /v2/wallet-codes/{codeId}/redeem

{
  "customerId": "cust_abc123"
}

Status Lifecycle

active → redeemed
active → expired
active → revoked

Managing Codes

View All Codes

Go to Product > Wallet Codes to see all codes with status, amount, customer, and dates.

Revoke a Code

1. Find the code in the list
2. Click the actions menu
3. Select Revoke

Revoking a code does not remove credit already redeemed.

Bulk Create

Use the API to create multiple codes programmatically for campaigns:

# Create 100 promotional codes
for i in $(seq 1 100); do
  curl -X POST /v2/wallet-codes \
    -d '{"amountCents": 1000, "codeType": "promotional"}'
done

Related

• Wallets Overview — How wallets work
• Managing Balances — Credit and debit operations
• Customer Portal — Customer code redemption