> ## Documentation Index
> Fetch the complete documentation index at: https://integration.wpay.com.au/llms.txt
> Use this file to discover all available pages before exploring further.
# Split tender
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](/reference/transactions/new-transaction) 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](/reference/gift-cards/new-gift-card). 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](/reference/transactions/new-transaction) 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 returns 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](/reference/gift-cards/list-buyer-gift-cards). This automatically archives inactive cards, freeing up space for new ones.
### Store gift card API request
```json theme={"system"}
{
"number": "6280005562385333923",
"pin": "5318",
"buyer_id": "2835cac4-6731-4dbf-a0d9-c286c5782f26"
}
```
### Store gift card API response
```json theme={"system"}
{
"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`](/reference/transactions/new-transaction#body-gift-cards) array.
### Request Example
Add new or saved gift cards information in the `gift-cards` array.
```json theme={"system"}
{
"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`
```json theme={"system"}
{
"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](/reference/gift-cards/new-gift-card). This API returns the gift-card `id` that can be used in a split tender transaction. Calling a [Transaction API](/reference/transactions/new-transaction) with `store = true` only saves the buyer's primary payment method, but not gift cards.
### Request Example (Stored Gift Cards)
```json theme={"system"}
{
"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`.
```json theme={"system"}
{
"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](/guides/payments/direct-api/paypal), [Afterpay](/guides/payments/direct-api/afterpay), and [Zip Pay](/guides/payments/direct-api/zip)) via direct API integrations:
1. When [calling the Transaction API](/guides/payments/direct-api/quick-start/transaction), include gift card details in the `gift-cards` array.
2. Handle the redirect flow to complete the transaction.
3. Call [GET Transaction](/reference/transactions/get-transaction) API to get the latest status of the transaction.
For a step-by-step integration guide, refer to the [Direct API guide](/guides/payments/direct-api/quick-start/overview).
## 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`.
```json theme={"system"}
{
"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`).
```json theme={"system"}
{
"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:
1. The primary payment method is authorized but placed on hold for manual review.
2. The gift cards are charged successfully.
3. 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.
```json theme={"system"}
{
"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](/reference/transactions/void-transaction) and [Capture](/reference/transactions/capture-transaction) APIs only apply to primary payment methods and do not affect gift card redemptions.