Checkout Integration

Wallets integrate directly into the RevKeen checkout flow. Customers can pay partially or fully from their wallet balance, reducing or eliminating card processing fees.

Auto-Apply Wallet Balance

When Auto-apply at checkout is enabled in your wallet settings, the checkout page automatically applies the customer's available wallet balance to the invoice total.

• If the wallet covers the full amount, no card payment is required
• If the wallet covers part of the amount, the customer pays the remainder by card
• Customers can opt out by unchecking "Use wallet balance" at checkout

"Have a Code?" Input

Every checkout page includes a code redemption field:

1. Customer enters a wallet code in the "Have a code?" input
2. The code is validated in real-time
3. On success, the credit is added to the customer's wallet
4. The newly added balance is applied to the invoice

This works for both existing customers and guest checkout (code credit is applied as a direct invoice deduction for guests).

Payment Scenarios

Full Wallet Payment

When the wallet balance covers the entire invoice:

Invoice total: £50.00
Wallet balance: £75.00
Card charge: £0.00 (no processing fees!)
New wallet balance: £25.00

Partial Payment (Wallet + Card)

When the wallet balance covers part of the invoice:

Invoice total: £50.00
Wallet balance: £20.00
Wallet applied: £20.00
Card charge: £30.00
New wallet balance: £0.00

No Wallet Balance

Standard card payment flow. The wallet section is hidden if the customer has no balance.

Hold/Capture/Release Pattern

Wallet payments use a reservation pattern to ensure atomicity:

Flow

1. Hold — When the customer clicks "Pay", a hold is created for the wallet portion
2. Card charge — If a card payment is needed for the remainder, it's processed
3. Capture — If everything succeeds, the wallet hold is captured (balance deducted)
4. Release — If the card charge fails, the wallet hold is released (balance restored)

Why Holds?

Without holds, a race condition could occur:

• Customer A uses wallet balance at checkout
• Card payment fails
• Meanwhile, customer A's balance was already deducted
• Now they've lost money with no purchase

Holds prevent this by reserving but not deducting until the full payment is confirmed.

Hold Expiry

Holds expire automatically after 30 minutes. This prevents balance from being locked indefinitely if a checkout session is abandoned.

Guest Checkout Code Redemption

For guest checkout (no customer account):

1. Guest enters a wallet code at checkout
2. If the code is unrestricted (not tied to a specific customer), it's accepted
3. The code value is applied as a direct deduction on the invoice
4. No wallet account is created — the credit is consumed immediately

API Flow (Developer Reference)

For custom checkout integrations:

1. GET /v2/wallet/customers/{customerId}/balance
   → Check available balance

2. POST /v2/wallet/customers/{customerId}/hold
   → Reserve wallet amount for checkout

3. Process card payment for remainder (if any)

4a. POST /v2/wallet/customers/{customerId}/hold/{holdId}/capture
    → Payment succeeded: capture the hold

4b. POST /v2/wallet/customers/{customerId}/hold/{holdId}/release
    → Payment failed: release the hold

Related

• Wallets Overview — What wallets are and how they work
• Managing Balances — Credit and debit operations
• Wallet Codes — Redeemable credit codes
• Checkout — General checkout configuration