Wpay supports split tender transactions across one primary payment method and one or more gift cards. The maximum number of gift cards that can be redeemed in a split tender is 10. The primary payment method can be a scheme card (including digital wallets for scheme cards, such as Apple Pay and Google Pay) or an alternative payment method such as PayPal, Afterpay, or Zip.
Overview of split tender
To process a split tender, call the Transaction API with a combination of a primary payment method and gift cards.
Key considerations:
- A transaction must include at least one primary payment method or one gift card. You may process a gift card only transaction or a split tender transaction between a primary payment method and gift cards.
- Gift cards are treated separately from the primary payment method in the API requests and responses.
- The
gift_card_redemptions array in the response contains details of all gift card redemptions.
- The
amount field represents the total transaction amount (primary payment method + gift cards).
- The primary payment method is always processed first, followed by gift cards.
- Gift card redemptions are always processed as direct capture.
- Split tender transactions are atomic :
- If the primary payment method fails, no gift card redemption occurs.
- If any gift card redemption fails, the transaction is reversed:
- The primary payment method is voided.
- Successfully redeemed gift cards are refunded.
- Unredeemed gift cards are skipped.
Storing gift cards in a buyer’s wallet
You can store gift cards in a buyer’s wallet using the Store Gift Card API. This is the only API that can be used to securely vault a single gift card and validates it against the active gift card service.
Calling a Transaction API with store = true only saves the buyer’s primary payment method, but not gift cards.
Key considerations:
- Only unique, active (non-expired) gift cards can be stored for a buyer.
- The API will return a
gift card id that can be used in gift card only or split tender transactions.
- By default, buyers can store up to 10 gift cards.
- To remove expired or empty gift cards, call the GET /buyers/gift-cards. This automatically archives inactive cards, freeing up space for new ones.
Store gift card API request
{
"number": "6280005562385333923",
"pin": "5318",
"buyer_id": "2835cac4-6731-4dbf-a0d9-c286c5782f26"
}
Store gift card API response
{
"type": "gift-card",
"id": "84467b52-8b3d-4a23-bdce-3a56bbdd700c",
"merchant_account_id": "default",
"gift_card_service": {
"type": "gift-card-service",
"id": "8b1242fb-2adf-4b72-8c15-6cbc1963cde4",
"gift_card_service_definition_id": "qwikcilver-gift-card",
"display_name": "Qwikcilver"
},
"bin": "628000",
"sub_bin": "556",
"last4": "3923",
"expiration_date": "2026-03-14T13:59:59.999999+00:00",
"buyer": {
"type": "buyer",
"id": "2835cac4-6731-4dbf-a0d9-c286c5782f26",
"merchant_account_id": "default",
"display_name": "John Smyth",
"external_identifier": null,
"billing_details": {
"first_name": "John",
"last_name": "Smyth",
"email_address": "john.smyth@gmail.com",
"phone_number": null,
"address": {
"city": "Surry Hills",
"country": "AU",
"postal_code": "2028",
"state": "NSW",
"state_code": "AU-NSW",
"house_number_or_name": "372",
"line1": "Elizabeth St",
"organization": "Org"
},
"tax_id": null
},
"account_number": null,
"created_at": "2023-11-30T23:34:49.486829+00:00",
"updated_at": "2023-11-30T23:36:46.311226+00:00"
},
"created_at": "2025-03-26T00:17:49.656567+00:00",
"updated_at": "2025-03-26T00:17:49.656567+00:00"
}
Gift card only transaction
To process a payment using only gift cards, set payment_method to null and include gift card details under the gift-cards array.
Request Example
Add new or saved gift cards information in the gift-cards array.
{
"amount": 1299,
"currency": "AUD",
"intent": "authorize",
"payment_source": "ecommerce",
"Payment_method" : null,
"gift-cards": [{
"number": "6280005567112008599",
"pin": "5962",
"amount": 1000
},{
"number": "6280005562385333923",
"pin": "5318",
"amount": 299
}]
...
}
Response Highlights
- intent_outcome` reflects the overall transaction result.
status represents the state of the primary payment method. In gift card only transactions, this does not really matter as there is no primary payment method involved (primary payment method is null).amount represents the total amount charged. authorized_amount is 0 since there is no primary payment method being charged.- The
gift_card_redemptions array contains the redemption details including the gift_card_redemptions.status, gift_card_redemptions.error_code, and gift_card_redemptions.refunded_amount.
- If multiple gift cards are used,
multi_tender is true.
- If there is only one gift card,
multi_tender is false
{
"type": "transaction",
"id": "0d4d2f8b-c202-470d-aadb-cb175824a0c8",
"amount": 1299,
"status": "authorization_succeeded",
"gift_card_redemptions": [
{
"type": "gift-card-redemption",
"id": "5fdd5d98-55a8-43b3-8b09-e35b904d5d97",
"status": "succeeded",
"amount": 1000,
"refunded_amount": 0,
"gift_card_service_redemption_id": "23598320",
"error_code": null,
"raw_error_code": null,
"raw_error_message": null,
"gift_card": {
"type": "gift-card",
"id": null,
"bin": "628000",
"sub_bin": "556",
"last4": "8599"
}
},
{
"type": "gift-card-redemption",
"id": "d4f45643-8dbb-456d-b0ba-a09e5778d12c",
"status": "succeeded",
"amount": 299,
"refunded_amount": 0,
"gift_card_service_redemption_id": "23598321",
"error_code": null,
"raw_error_code": null,
"raw_error_message": null,
"gift_card": {
"type": "gift-card",
"id": null,
"bin": "628000",
"sub_bin": "556",
"last4": "3923"
}
}
],
"gift_card_service": {
"type": "gift-card-service",
"id": "8b1242fb-2adf-4b72-8c15-6cbc1963cde4",
"gift_card_service_definition_id": "qwikcilver-gift-card",
"display_name": "Qwikcilver"
},
"payment_source": "ecommerce",
"intent_outcome": "succeeded",
"multi_tender": true,
...
}
Split Tender Transaction (Scheme Card + Gift Cards)
To process a split tender transaction with a scheme card and gift cards, specify the scheme card under payment-methods object and include gift cards in the gift-cards array. You may either include new gift cards (with gift card number and pin) or stored gift cards (with gift card id).
To store gift cards, use the Store gift card API. This API returns the gift-card id that can be used in a split tender transaction. Calling a Transaction API with store = true only saves the buyer’s primary payment method, but not gift cards.
Request Example (Stored Gift Cards)
{
"amount": 1599,
"currency": "AUD",
"intent": "authorize",
"payment_source": "ecommerce",
"payment_method": {
"method": "card",
"number": "4622943127013705",
"expiration_date": "03/30",
"external_identifier" : null,
"security_code": "100",
"redirect_url": "https://example.com/"
},
"gift-cards": [{
"id": "5c3ba1d8-f418-416f-9493-5abf23e0d05d",
"amount": 1000
},{
"id": "4b74e655-bf33-4952-83a3-149cfff43817",
"amount": 299
}]
...
}
Response Highlights
intent_outcome represents the overall success/failure of the transaction.amount represents the total amount charged including the scheme card and all gift cards.- The
gift_card_redemptions array contains gift card processing results.
- All of the fields outside of the
gift_card_redemptions array are related to the primary payment method only.
multi_tender is always set to true.
{
"id": "f82bbc79-c9be-4d2a-811c-2e38740ae230",
"amount": 1599,
"status": "authorization_succeeded",
"authorized_amount": 300,
"captured_amount": 0,
"intent": "authorize",
"payment_method": {
"details": {
"bin": "462294",
"card_type": "debit",
"card_issuer_name": null
},
"scheme": "visa",
"id": "25666304-81cc-46e3-b68b-5d60694a51d5",
...
},
"gift_card_redemptions": [
{
"type": "gift-card-redemption",
"id": "4d2c0c21-143e-455f-a1cb-f17f48bfd2cc",
"status": "succeeded",
"amount": 1000,
"refunded_amount": 0,
"gift_card_service_redemption_id": "23603110",
"error_code": null,
"raw_error_code": null,
"raw_error_message": null,
"gift_card": {
"type": "gift-card",
"id": "5c3ba1d8-f418-416f-9493-5abf23e0d05d",
"bin": "628000",
"sub_bin": "556",
"last4": "8599"
}
},
{
"type": "gift-card-redemption",
"id": "95de3b3a-db97-4361-9463-ee4c35b469e3",
"status": "succeeded",
"amount": 299,
"refunded_amount": 0,
"gift_card_service_redemption_id": "23603111",
"error_code": null,
"raw_error_code": null,
"raw_error_message": null,
"gift_card": {
"type": "gift-card",
"id": "4b74e655-bf33-4952-83a3-149cfff43817",
"bin": "628000",
"sub_bin": "556",
"last4": "3923"
}
}
],
"payment_service": {
"type": "payment-service",
"id": "2a931220-3d0e-484d-8b0f-91b9cd474c01",
"payment_service_definition_id": "cybersource-card",
"method": "card",
"display_name": "Cybersource - wpay_gr4vy_test with 3DS"
},
"gift_card_service": {
"type": "gift-card-service",
"id": "8b1242fb-2adf-4b72-8c15-6cbc1963cde4",
"gift_card_service_definition_id": "qwikcilver-gift-card",
"display_name": "Qwikcilver"
},
"intent_outcome": "succeeded",
"multi_tender": true
...
}
Split Tender Transaction (Alternative Payment Method + Gift Cards)
You can process a split tender using an alternative payment method (such as PayPal, Afterpay, and Zip Pay) via direct API integrations:
- When calling the Transaction API, include gift card details in the
gift-cards array.
- Handle the redirect flow to complete the transaction.
- Call GET Transaction API to get the latest status of the transaction.
For a step-by-step integration guide, refer to the Direct API guide.
Handling Split Tender Failures
In principle, the primary payment method is processed first before gift cards to prevent complications. There are scenarios where we will fail or decline such as insufficient funds or the transaction after a certain time period has lapsed (e.g. buyer authentication/approval abandonment). Here, charging gift cards first would mean that the gift card amount will not be refunded until the transaction is canceled at a later time.
Scenario 1: Failed Gift Card
If a gift card redemption fails while the primary payment method succeeds, the transaction is reversed:
intent_outcome = failed.- The primary payment method is voided (
status: authorization_voided)
- Successful gift card redemptions are refunded.
- Failed gift cards display
status = failed with an error_code.
{
"id": "9bd8581c-593e-463e-a25b-90e2022130fb",
"amount": 1599,
"status": "authorization_voided",
"authorized_amount": 300,
"payment_method": {
"type": "payment-method",
"details": {
"bin": "462294",
"card_type": "debit",
"card_issuer_name": null
},
"expiration_date": "03/30",
...
},
"method": "card",
"error_code": null,
"raw_response_code": null,
"raw_response_description": null,
"gift_card_redemptions": [
{
"type": "gift-card-redemption",
"id": "6054f8ff-0edd-44fb-8c45-3bac2a099e21",
"status": "failed",
"amount": 1000,
"refunded_amount": 0,
"gift_card_service_redemption_id": null,
"error_code": "operation_canceled",
"raw_error_code": "0",
"raw_error_message": null,
"gift_card": {
"type": "gift-card",
"id": null,
"bin": "628000",
"sub_bin": "556",
"last4": "8599"
}
},
{
"type": "gift-card-redemption",
"id": "e709c330-9c12-468f-a7b2-906b3a94532e",
"status": "failed",
"amount": 299,
"refunded_amount": 0,
"gift_card_service_redemption_id": null,
"error_code": "expired_card",
"raw_error_code": "10001",
"raw_error_message": "Card expired.",
"gift_card": {
"type": "gift-card",
"id": null,
"bin": "628000",
"sub_bin": "556",
"last4": "7864"
}
}
],
"authorized_at": "2025-03-16T06:39:45.100925+00:00",
"voided_at": "2025-03-16T06:39:46.871247+00:00",
"multi_tender": true,
"intent_outcome": "failed",
...
}
Scenario 2: Failed Primary Payment Method
If the primary payment method fails or is declined::
intent_outcome = failed.- The
status of the primary payment method would either be authorization_failed or authorization_declined.
- Gift card redemptions are not performed (
status = skipped).
{
"type": "transaction",
"id": "c33c0762-2300-4a9e-a897-8a418a42254a",
"reconciliation_id": "5wOw5tz0J7evgOs6CdsSba",
"merchant_account_id": "default",
"currency": "AUD",
"amount": 1499,
"status": "authorization_declined",
"authorized_amount": 0,
"captured_amount": 0,
"refunded_amount": 0,
"gift_card_redemptions": [
{
"type": "gift-card-redemption",
"id": "0b7a4c58-dae8-4e87-be70-edfa834b0c84",
"status": "skipped",
"amount": 1000,
"refunded_amount": 0,
"gift_card_service_redemption_id": null,
"error_code": null,
"raw_error_code": null,
"raw_error_message": null,
"gift_card": {
"type": "gift-card",
"id": null,
"bin": "628000",
"sub_bin": "556",
"last4": "8599"
}
},
{
"type": "gift-card-redemption",
"id": "5fda97d0-63ee-466c-9fa7-0e7635c9fff3",
"status": "skipped",
"amount": 299,
"refunded_amount": 0,
"gift_card_service_redemption_id": null,
"error_code": null,
"raw_error_code": null,
"raw_error_message": null,
"gift_card": {
"type": "gift-card",
"id": null,
"bin": "628000",
"sub_bin": "556",
"last4": "3923"
}
}
],
"intent_outcome": "failed",
"multi_tender": true,
...
}
Split Tender and Anti-Fraud Manual Review
In scenarios where the anti-fraud engine returns a review decision in a split tender transaction:
- The primary payment method is authorized but placed on hold for manual review.
- The gift cards are charged successfully.
- If the manual review later results in a rejection, the transaction outcome will be:
intent_outcome: failed- The primary payment method’s
status: authorization_voided
- Gift cards will be refunded.
Refunding back to gift cards
Important: You should not refund back to gift cards for the following reasons:
- The buyer may no longer be available to be notified of the refund, or
- The buyer may not have the original gift card with them at the time of the refund.
Instead, the recommendation is to issue a new gift card or store credit to compensate the buyer.
{
"type": "transaction",
"id": "f82bbc79-c9be-4d2a-811c-2e38740ae230",
"currency": "AUD",
"amount": 1599,
"status": "authorization_voided",
"authorized_amount": 300,
"captured_amount": 0,
"refunded_amount": 0,
"intent": "authorize",
"voided_at": "2025-03-16T06:39:46.871247+00:00",,
"payment_method": {
"type": "payment-method",
"approval_url": null,
"country": "AU",
"currency": null,
"details": {
"bin": "462294",
"card_type": "debit",
"card_issuer_name": null
},
"expiration_date": "03/30",
"fingerprint": "a8e201df83226560fa6d0904e2a8aba393ac22ecc6488b54939261b7f97bb9ba",
"label": "3705",
"last_replaced_at": null,
"method": "card",
"mode": "card",
"scheme": "visa",
"id": "25666304-81cc-46e3-b68b-5d60694a51d5",
"approval_target": null,
"external_identifier": null,
"payment_account_reference": null
},
"gift_card_redemptions": [
{
"type": "gift-card-redemption",
"id": "4d2c0c21-143e-455f-a1cb-f17f48bfd2cc",
"status": "succeeded",
"amount": 1000,
"refunded_amount": 0,
"gift_card_service_redemption_id": "23603110",
"error_code": null,
"raw_error_code": null,
"raw_error_message": null,
"gift_card": {
"type": "gift-card",
"id": "5c3ba1d8-f418-416f-9493-5abf23e0d05d",
"bin": "628000",
"sub_bin": "556",
"last4": "8599"
}
},
{
"type": "gift-card-redemption",
"id": "95de3b3a-db97-4361-9463-ee4c35b469e3",
"status": "succeeded",
"amount": 299,
"refunded_amount": 0,
"gift_card_service_redemption_id": "23603111",
"error_code": null,
"raw_error_code": null,
"raw_error_message": null,
"gift_card": {
"type": "gift-card",
"id": "4b74e655-bf33-4952-83a3-149cfff43817",
"bin": "628000",
"sub_bin": "556",
"last4": "3923"
}
}
],
"instrument_type": "pan",
"pending_review": false,
"error_code": null,
"raw_response_code": null,
"raw_response_description": null,
"auth_response_code": "00",
"avs_response_code": "match",
"cvv_response_code": "match",
"payment_source": "ecommerce",
"scheme_transaction_id": "016153570198200",
"payment_service_transaction_id": "7419360017276878403814",
"intent_outcome": "succeeded",
"multi_tender": true
...
}
Post-auth operations
Void and Capture APIs only apply to primary payment methods and do not affect gift card redemptions.
