Guide

Rewards with gift & prepaid cards

A card makes a reward feel like a reward: a gift card from a brand the recipient knows, or a prepaid card they can spend anywhere. With Xtrm, each card is one item in a batch payment, so you can reward a whole team in a single request. In this guide you reward two people, one with each kind of card. You pick a gift card from Xtrm's catalog and check its value, find the prepaid card for your currency, submit both rewards in one batch, and track each one until the card is on its way. Every sample runs against the sandbox once you swap in the SKUs that your own catalog calls return (see Sandbox limits).

#Gift card or prepaid card?

Each reward is one item in a batch, and every item names its own send method, so one batch can carry gift cards and prepaid cards together. Each method pairs with its own catalog: send a SKU from the gift card catalog with XTR94505, and a SKU from the prepaid card catalog with XTR94503. A gift card is a choice between brands and products. A prepaid card is the prepaid card for the batch's currency: the item still needs its SKU, and the current release orders the first prepaid card for that currency (see step 3).

Digital gift cardPrepaid card
SendMethodIdXTR94505XTR94503
Browse the catalogGetDigitalGiftCardsGetPrepaidCards
Check one SKUGetGiftCardDetailsGetPrepaidCardDetails
Catalog request keys (list, details)GetGiftCards › request, GetGiftCards › RequestGetPrepaidCards › Request for both
Item DestinationEmail and SKU, both requiredEmail and SKU, both required
RecipientAn individual recipient (PAT…) only; a business recipient fails with SENDMETHODID_NOT_FOUNDAn individual recipient (PAT…) only; a business recipient fails with SENDMETHODID_NOT_FOUND
rewardType in the cataloggift card or donationcash equivalent

Batch payments are wallet-first. Each item credits the recipient's wallet in the batch's currency (the currency of your source wallet), then Xtrm orders the card from the card provider. Without a WalletId, Xtrm credits the recipient's oldest active Standard wallet in that currency. If the recipient's account has no active wallet of any type in that currency, Xtrm creates one named Wallet - <currency code>. If its only active wallets in that currency aren't Standard wallets, Xtrm creates none and the item fails with WALLET_AUTO_CREATE_FAILED; send a WalletId for such a recipient. While Xtrm orders the card, the item shows RetainedInWallet, usually only briefly, and it moves on to Success once the card provider accepts the order. If the item is still RetainedInWallet once the batch status is final, the card order didn't go through and the money stays in the recipient's Xtrm wallet; see The item stays RetainedInWallet and How batch payments work.

The card provider emails the card's digital credentials to the address you send in Destination.Email, whatever EmailNotification says. No batch payment response carries them, and no API resends them, so a mistyped address can't be fixed through the API. Check each address before you submit, and track each reward by its status, not by its credentials.

#Before you begin

  • Sandbox credentials and an access token in the XTRM_ACCESS_TOKEN environment variable. See Authentication and Sandbox & environments.
  • Your company's account number, the SPN that owns your API credentials (SPN1111222 in the samples). You send it as IssuerAccountNumber.
  • A funded company wallet and its ID (122181 in the samples). GetCompanyWallets lists your wallets with their WalletCurrency and WalletBalance. The wallet you pay from sets the currency of the batch, so pick one in the currency of the rewards. In the sandbox, Xtrm credits test funds to your wallets after approving your IP addresses; see Test funds. To add more, see Fund your wallet.
  • Each recipient's PAT number, the individual recipient you reward (PAT1111002 and PAT9999888 in the samples). A batch pays existing Xtrm accounts only, so every recipient needs an account before you submit the batch. Find one by email address with CheckUserExist, or create one with CreateUser first; see Pay individual recipients.
  • An email address for each reward. The card provider emails the card's credentials there. The samples use [email protected] and [email protected].
  • Optionally, a webhook endpoint, so Xtrm can notify you as rewards are processed. See Get notified with webhooks.

#Pay card rewards in a batch

  1. Browse the gift card catalog

    Call GetDigitalGiftCards with the currency of the wallet you'll pay from. The cards on offer vary by currency.

    Watch the envelope: the root key is GetGiftCards, not the operation name in the URL, and the inner key is a lowercase request.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/GiftCard/GetDigitalGiftCards" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "GetGiftCards": {
        "request": {
          "IssuerAccountNumber": "SPN1111222",
          "Currency": "USD"
        }
      }
    }'

    The response lists card brands in GiftCard, each with display fields and its products in items, one per sku. Abridged: the HTML text fields (description, disclaimer, shortDescription, terms) and the second Acme product are left out.

    Response (excerpt)
    {
      "GetGiftCardResponse": {
        "GetGiftCardResult": {
          "GiftCard": [
            {
              "brandName": "Acme Retail Emporium",
              "imageUrls": [
                {
                  "Img80W": "https://example.com/images/brands/acme-80w.png",
                  "Img130w": "https://example.com/images/brands/acme-130w.png",
                  "Img200W": "https://example.com/images/brands/acme-200w.png",
                  "Img300W": "https://example.com/images/brands/acme-300w.png"
                }
              ],
              "items": [
                {
                  "sku": "U935268",
                  "rewardName": "Acme Retail Emporium Gift Card $25.00",
                  "currencyCode": "USD",
                  "status": "Active",
                  "valueType": "FIXED_VALUE",
                  "rewardType": "gift card",
                  "maxValue": 0,
                  "minValue": 0,
                  "faceValue": 25,
                  "countries": ["US", "AS", "IO", "EC", "SV", "GU", "MH", "FM", "NF", "MP", "PW", "PA", "PR", "TC", "UA", "UM", "VG", "VI", "ZW"]
                }
              ]
            },
            {
              "brandName": "Global Bistro & Grill",
              "imageUrls": [
                {
                  "Img80W": "https://example.com/images/brands/bistro-80w.png",
                  "Img130w": "https://example.com/images/brands/bistro-130w.png",
                  "Img200W": "https://example.com/images/brands/bistro-200w.png",
                  "Img300W": "https://example.com/images/brands/bistro-300w.png"
                }
              ],
              "items": [
                {
                  "sku": "U935270",
                  "rewardName": "Global Bistro & Grill eGift Card",
                  "currencyCode": "USD",
                  "status": "Active",
                  "valueType": "VARIABLE_VALUE",
                  "rewardType": "gift card",
                  "maxValue": 500,
                  "minValue": 5,
                  "faceValue": 0,
                  "countries": ["US", "AS", "IO", "EC", "SV", "GU", "MH", "FM", "NF", "MP", "PW", "PA", "PR", "TC", "UA", "UM", "VG", "VI", "ZW"]
                }
              ]
            }
          ],
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Each product's valueType is one of two values, and it tells you which value fields apply:

    • FIXED_VALUE: a set denomination. The price is in faceValue, and minValue and maxValue are 0. U935268 is a 25 USD card.
    • VARIABLE_VALUE: any amount from minValue to maxValue, and faceValue is 0. U935270 takes 5 to 500 USD.

    countries lists the two-letter codes of the countries that use the card's currency. Only the catalog calls return it: the details calls, such as the one in step 2, don't.

    For a reward picker, use brandName, an image from imageUrls (note the lowercase w in Img130w), shortDescription and terms. The text fields contain HTML in the example, so sanitize them before you render them.

    Keep for later: the sku (U935268), and countries if you need it.

  2. Check the gift card's value range

    Before you add a reward to a batch, look up its product with GetGiftCardDetails, for example when someone picked it in your UI or you cached the catalog.

    The root key is GetGiftCards again, and this time the samples spell the inner key Request, with a capital R. Xtrm matches JSON property names in any case, so request works too.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/GiftCard/GetGiftCardDetails" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "GetGiftCards": {
        "Request": {
          "IssuerAccountNumber": "SPN1111222",
          "SKU": "U935268"
        }
      }
    }'

    The brand comes back in GiftCardDetail, with the matching product in items. The product has no countries: take it from the catalog call if you need it. Abridged: the HTML text fields and imageUrls are left out.

    Response (excerpt)
    {
      "GetGiftCardResponse": {
        "GetGiftCardDetailsResult": {
          "GiftCardDetail": {
            "brandName": "Acme Retail Emporium",
            "items": [
              {
                "sku": "U935268",
                "rewardName": "Acme Retail Emporium Gift Card $25.00",
                "currencyCode": "USD",
                "status": "Active",
                "valueType": "FIXED_VALUE",
                "rewardType": "gift card",
                "maxValue": 0,
                "minValue": 0,
                "faceValue": 25
              }
            ]
          },
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Work out the reward amount from the value rules: faceValue for a FIXED_VALUE product, or a value from minValue to maxValue for a VARIABLE_VALUE one. Also check that currencyCode matches the currency of the wallet you'll pay from, and we recommend checking that status is Active. During processing, before any money moves, a gift card in another currency fails with CURRENCY_MISMATCH, and an amount that doesn't fit the card fails with INVALID_CARD_AMOUNT, so validate both here.

    Keep for later: the sku and the amount (25.00 for U935268).

  3. Find the prepaid card for your currency

    Call GetPrepaidCards with the same currency. Here the root key is GetPrepaidCards and the inner key is Request with a capital R.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/GiftCard/GetPrepaidCards" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "GetPrepaidCards": {
        "Request": {
          "IssuerAccountNumber": "SPN1111222",
          "Currency": "USD"
        }
      }
    }'

    The prepaid card catalog lists the prepaid cards for the currency, in an array named GiftCard with the same fields as the gift card catalog. Abridged: the HTML text fields are left out.

    Response (excerpt)
    {
      "GetPrepaidCardResponse": {
        "GetPrepaidCardResult": {
          "GiftCard": [
            {
              "brandName": "Visa® Prepaid Card USD",
              "imageUrls": [
                {
                  "Img80W": "https://example.com/images/brands/visa-80w.png",
                  "Img130w": "https://example.com/images/brands/visa-130w.png",
                  "Img200W": "https://example.com/images/brands/visa-200w.png",
                  "Img300W": "https://example.com/images/brands/visa-300w.png"
                }
              ],
              "items": [
                {
                  "sku": "PREP9001",
                  "rewardName": "Visa® Prepaid Card USD",
                  "currencyCode": "USD",
                  "status": "Active",
                  "valueType": "VARIABLE_VALUE",
                  "rewardType": "cash equivalent",
                  "maxValue": 1000,
                  "minValue": 5,
                  "faceValue": 0,
                  "countries": ["US", "AS", "IO", "EC", "SV", "GU", "MH", "FM", "NF", "MP", "PW", "PA", "PR", "TC", "UA", "UM", "VG", "VI", "ZW"]
                }
              ]
            }
          ],
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    PREP9001 is the USD prepaid card: VARIABLE_VALUE, from 5 to 1000 USD, with the rewardType cash equivalent. We recommend showing the brand's terms and disclaimer to the recipient.

    A prepaid card item must send this sku in Destination.SKU. While it processes the item, Xtrm checks that the SKU is one of the prepaid cards for the batch's currency and that the amount fits its value range, before any money moves. The current release then orders the first prepaid card for the batch's currency, so treat a prepaid card as that currency's prepaid card, not a choice between products. To look a prepaid SKU up again later, use GetPrepaidCardDetails.

    Keep for later: the sku (PREP9001) and an amount in its range (100.00 here).

  4. Pay the rewards in a batch

    Submit both rewards in one call to BatchTransfer. The fields sit at the root of the body, with no envelope:

    FieldWhat to send
    IssuerAccountNumberYour company's SPN.
    SourceWalletIdThe company wallet to pay from, as an integer. It must be your company's own active wallet, otherwise the whole request gets 403 FORBIDDEN. It sets the currency of the batch.
    CustomerBatchIdRequired. Your ID for the batch: Xtrm never generates one.
    EmailNotificationOptional JSON boolean, false by default. true emails each recipient a payment-received message at their own address when their wallet is credited. It doesn't control the card credentials, which always go to Destination.Email.
    Items[].CustomerTransactionIdRequired. Your ID for this reward: Xtrm never generates one.
    Items[].RecipientIdThe individual recipient's PAT number. A business recipient fails with SENDMETHODID_NOT_FOUND.
    Items[].AmountThe amount from step 2 or 3, as a JSON number greater than 0, with at most 2 decimal places. It must fit the card: the face value of a fixed-value card, or from the minimum to the maximum of a variable-value card.
    Items[].SendMethodIdXTR94505 for a gift card, XTR94503 for a prepaid card.
    Items[].DescriptionOptional note, up to 1,024 characters. Xtrm copies it to the wallet transactions the reward creates, in your wallet and the recipient's, where the recipient sees it. Start it with the item's CustomerTransactionId, as the samples do, so you can find those transactions later; see Track & reconcile payments.
    Items[].Destination.EmailRequired for both card methods, and it must be a valid address. The card provider emails the card's digital credentials there.
    Items[].Destination.SKURequired for both card methods, at most 20 characters (the error message for a longer value says 30). The sku from the catalog that matches the send method: U935268 from step 1 for the gift card, PREP9001 from step 3 for the prepaid card.

    This batch rewards John Smith (PAT1111002) with the USD 25.00 gift card U935268, and Jane Doe (PAT9999888) with a USD 100.00 prepaid card. A batch can hold up to your account's item limit; more items fail with 422 LIMIT_EXCEEDED.

    Give every reward its own CustomerTransactionId, store both IDs with your reward records before you call, and never reuse an ID for a different payment, even in another batch. For the ID rules, see Batch and payment identifiers.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "IssuerAccountNumber": "SPN1111222",
      "SourceWalletId": 122181,
      "CustomerBatchId": "BATCH-REWARDS-0001",
      "EmailNotification": true,
      "Items": [
        {
          "CustomerTransactionId": "TXN-REWARDS-0001",
          "RecipientId": "PAT1111002",
          "Amount": 25,
          "SendMethodId": "XTR94505",
          "Description": "TXN-REWARDS-0001 Q3 Top Performer Contractor Reward",
          "Destination": {
            "Email": "[email protected]",
            "SKU": "U935268"
          }
        },
        {
          "CustomerTransactionId": "TXN-REWARDS-0002",
          "RecipientId": "PAT9999888",
          "Amount": 100,
          "SendMethodId": "XTR94503",
          "Description": "TXN-REWARDS-0002 Q3 Top Performer Contractor Reward",
          "Destination": {
            "Email": "[email protected]",
            "SKU": "PREP9001"
          }
        }
      ]
    }'

    Xtrm checks each item's format and responds right away. When at least one item passes, the response is 202, listing the items it queued in Accepted, not necessarily in request order, and the ones it refused in Rejected. If no item passes, nothing is stored and the response is 422, or 409 when an item already exists in this batch; see An item is rejected at submission. When both rewards pass, the response includes the following, with each Amount echoed as a JSON number with the decimals you sent, so 25 and 100 come back as 25.0 and 100.0:

    Response (excerpt)
    {
      "BatchTransferResponse": {
        "CustomerBatchId": "BATCH-REWARDS-0001",
        "Status": "Accepted",
        "Accepted": [
          {
            "CustomerTransactionId": "TXN-REWARDS-0002",
            "Amount": 100.0,
            "Currency": "USD",
            "SendMethodId": "XTR94503",
            "RecipientId": "PAT9999888"
          },
          {
            "CustomerTransactionId": "TXN-REWARDS-0001",
            "Amount": 25.0,
            "Currency": "USD",
            "SendMethodId": "XTR94505",
            "RecipientId": "PAT1111002"
          }
        ],
        "Rejected": []
      }
    }

    Accepted only means queued: Xtrm processes the items in the background, so no card exists yet, and nothing has been debited from your wallet. Confirm the outcome with the status endpoints in the next steps. Each Rejected entry has the CustomerTransactionId, a Key such as INVALID_FIELD, the Field that failed, such as Items[0].Destination.SKU, and a Message; see What can go wrong.

    Keep for later: the CustomerBatchId and, for each reward, its CustomerTransactionId and whether it was accepted or rejected.

  5. Track the batch payment

    Get the batch from the batch status endpoint, using your CustomerBatchId in the path. Set history=true to include each item's processing attempts, and page through the items with recordsToSkip and recordsToTake.

    curl -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-REWARDS-0001?recordsToSkip=0&recordsToTake=50&history=true" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN"

    The response returns the batch at the root, with no wrapper. Once Xtrm has processed both rewards, the history=true response looks like this:

    Response (excerpt)
    {
      "CustomerBatchId": "BATCH-REWARDS-0001",
      "Status": "Completed",
      "Currency": "USD",
      "ItemsCount": 2,
      "Items": [
        {
          "CustomerTransactionId": "TXN-REWARDS-0001",
          "Status": "Success",
          "RecipientId": "PAT1111002",
          "SendMethodId": "XTR94505",
          "Amount": "25.00",
          "LastUpdatedAt": "2026-10-27T17:12:31.4052317Z",
          "Attempts": [
            {
              "AttemptNo": 1,
              "Result": "Success",
              "ErrorCode": "SUCCESS",
              "CreatedAt": "2026-10-27T17:12:31.3986402Z",
              "CompletedAt": "2026-10-27T17:12:31.4052317Z"
            }
          ]
        },
        {
          "CustomerTransactionId": "TXN-REWARDS-0002",
          "Status": "Success",
          "RecipientId": "PAT9999888",
          "SendMethodId": "XTR94503",
          "Amount": "100.00",
          "LastUpdatedAt": "2026-10-27T17:12:36.2535086Z",
          "Attempts": [
            {
              "AttemptNo": 1,
              "Result": "Success",
              "ErrorCode": "SUCCESS",
              "CreatedAt": "2026-10-27T17:12:36.2476557Z",
              "CompletedAt": "2026-10-27T17:12:36.2535086Z"
            }
          ]
        }
      ],
      "Pagination": {
        "HasMore": false,
        "NextRecordsToSkip": 0
      }
    }

    Read each item's Status:

    • Accepted or Processing until the recipient's wallet is credited. This endpoint can also show Verified: the item passed validation and is waiting for the wallet credit.
    • RetainedInWallet while Xtrm orders the card from the recipient's wallet, usually only briefly. Don't act on it while the batch is still Processing.
    • Success when the card provider accepted the order and the card was emailed, as for both rewards here. It doesn't mean the recipient has claimed the card.
    • Failed when the item failed before the card was ordered, for example with SKU_NOT_FOUND or INVALID_CARD_AMOUNT. You can resubmit it after you fix the cause; see What can go wrong.
    • Still RetainedInWallet once the batch status is final: the card order didn't go through after the recipient's wallet was credited. The money has left your wallet and is in the recipient's Xtrm wallet, so you can't retry or resubmit the item, and the fee isn't refunded. Treat it like a wallet payment. See The item stays RetainedInWallet.

    The batch is Completed here because every item is Success. While items are still being processed it reads Processing, including while a card is being ordered, and when items fail it ends CompletedWithFailures or Failed. Confirm each item's Status before you act on the batch's status; see Batch and payment statuses. Poll at a modest interval, or use webhooks. When Pagination.HasMore is true, call again with recordsToSkip set to Pagination.NextRecordsToSkip to get the next page of items.

    Keep for later: each item's Status, LastUpdatedAt and, for failed attempts, the ErrorCode.

  6. Check one reward

    To answer "where's my reward?" for one recipient, or after a webhook, get a single item from the payment status endpoint, using the CustomerBatchId and CustomerTransactionId in the path. With history=true, the response includes every attempt.

    curl -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-REWARDS-0001/Items/TXN-REWARDS-0002?history=true" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN"

    The sample checks Jane Doe's prepaid card, TXN-REWARDS-0002. Here is its history=true response:

    Response
    {
      "CustomerBatchId": "BATCH-REWARDS-0001",
      "CustomerTransactionId": "TXN-REWARDS-0002",
      "Status": "Success",
      "RecipientId": "PAT9999888",
      "SendMethodId": "XTR94503",
      "Amount": "100.00",
      "Currency": "USD",
      "DeliveryType": "Prepaid Virtual Debit Card",
      "LastUpdatedAt": "2026-10-27T17:12:36.253Z",
      "Attempts": [
        {
          "AttemptNo": 1,
          "Result": "Success",
          "ErrorCode": "SUCCESS",
          "CreatedAt": "2026-10-27T17:12:09.3318405Z",
          "CompletedAt": "2026-10-27T17:12:36.253Z"
        }
      ]
    }

    DeliveryType is set once an item is Success: Prepaid Virtual Debit Card for a prepaid card (XTR94503), as here, and Digital Gift Cards for a gift card (XTR94505). A RetainedInWallet item reports Wallet, both while the card is being ordered and after the order has failed, and an Accepted, Processing or Failed item an empty string. Attempts lists each try, oldest first; this reward succeeded on its first attempt. This endpoint repeats the item's own times in every attempt's CreatedAt and CompletedAt, so order attempts by AttemptNo. A successful card item can also show two Success attempts with the same AttemptNo: treat them as one outcome.

    Keep for your records: the item's final Status, DeliveryType and LastUpdatedAt, with the attempt history if you reconcile failures.

#Get notified with webhooks

Xtrm can also notify your server with webhooks as it processes each reward, signed with HMAC-SHA256 in X-Signature. Xtrm sets up one endpoint per company account, in the sandbox and in production. To set it up, send your endpoint URL to your Account Manager or Customer Success Manager, or to [email protected]: Xtrm support configures the endpoint and sets up its signing secret with you. See Webhooks for payloads, signature verification and retries. No event reports RetainedInWallet. A card item's Batch.Item.Completed has Status Success whether or not the order went through, so read its DeliveryType: Digital Gift Cards or Prepaid Virtual Debit Card means it did, and Wallet means it didn't and the item stays RetainedInWallet. Confirm final statuses with the status endpoints, as in steps 5 and 6.

#What can go wrong

#An item is rejected at submission

A card item comes back in Rejected with Key INVALID_FIELD, ErrorCode 422 and the failing Field, for example Items[0].Destination.SKU, when Destination.Email is missing or isn't a valid address, Destination.SKU is missing or longer than 20 characters, or Amount is missing, zero or negative. The other items are still processed. A rejected item was never stored and has no attempt. To fix and resend it, see Items rejected at submission.

#SKU_NOT_FOUND: the card can't be issued

The item's Status is Failed and its attempt's ErrorCode is SKU_NOT_FOUND. For a gift card, the SKU isn't in Xtrm's catalog. For a prepaid card, it isn't one of the prepaid cards for the batch's currency. Nothing was debited. Related codes fail the same way, before any money moves:

  • CURRENCY_MISMATCH (gift cards only): the SKU's currency isn't the batch's currency, or its reward type isn't a gift card or donation.
  • CURRENCY_INVALID (prepaid cards only): Xtrm offers no prepaid card in the batch's currency.
  • INVALID_CARD_AMOUNT: the amount doesn't fit the card (see The amount doesn't fit the card).

Xtrm doesn't check whether a SKU is still active at this point. To fix the item, look the card up again in the catalog that matches its send method (GetDigitalGiftCards for XTR94505, GetPrepaidCards for XTR94503), in the currency of the source wallet. Then resubmit the item under the same CustomerBatchId and CustomerTransactionId, with the corrected SKU and every other field: a retry replaces the whole stored item. If the SKU came from the other catalog, send the reward as a new item with a new CustomerTransactionId instead. For every code, see Error codes on attempts, and for resubmitting, Resubmit failed payments.

#The amount doesn't fit the card

An amount that isn't a fixed-value card's faceValue, or that falls outside a variable-value card's minValue to maxValue, fails the item during processing with INVALID_CARD_AMOUNT, before any money moves. Check the amount against the catalog before you add the item, as in steps 2 and 3, and resubmit a failed item with the corrected Amount and every other field. A gift card is checked again against the live catalog when it's ordered; if the amount no longer fits then, the attempt fails with INVALID_CARD_AMOUNT and the item stays RetainedInWallet.

#The item stays RetainedInWallet

Every card item passes through RetainedInWallet while Xtrm orders the card, so wait while the batch is Processing. An item that is still RetainedInWallet once the batch status is final (CompletedWithFailures or Failed) has stuck: the card order didn't go through after the recipient's wallet was credited, and Xtrm won't try again. The money has left your wallet and is in the recipient's Xtrm wallet, the fee isn't refunded, and you can't retry or resubmit the item.

Treat it like a wallet payment. The recipient can transfer it out themselves in the Xtrm web app, or you can request the transfer for them with UserWithdrawFund and their one-time password. That transfer is made only when a response has PaymentStatus Completed and a PaymentTransactionId: the first response, with Success: true, only sends the code. See When a payment stays RetainedInWallet. This guide's batch sets EmailNotification to true, so Xtrm emailed the recipient when the money reached their wallet.

Request the item with history=true: its newest attempt has Result Failed and an ErrorCode that says why the order failed, for example TEMPORARY_ERROR when the card provider declined the order. For every delivery code, see Delivery stage.

#The wallet runs short

An attempt that fails with INSUFFICIENT_BALANCE found less in your source wallet than the item's Amount plus its fee when Xtrm processed it. Nothing was debited for that item, and later, smaller items can still succeed. Fund your wallet, then resubmit the item with the same CustomerBatchId and CustomerTransactionId. To avoid it, check WalletBalance with GetCompanyWallets before you submit, and leave room for the fees.

#Duplicates and retries

Resubmit a Failed reward under its original CustomerBatchId and CustomerTransactionId, and only the failed ones: Xtrm records a new attempt and leaves the others as they are. Never reuse a CustomerTransactionId for a different reward: under a different CustomerBatchId it's a new payment, and Xtrm pays it. If a submit call times out, resend the identical request. If the latest attempt failed with TEMPORARY_ERROR, contact Xtrm support before you resubmit. For the full rules, see Retries & idempotency and A safe retry pattern.

#Sandbox limits

No real money moves in the sandbox. Otherwise the sandbox works the same as production: batch payments go through the same processing there, and a card item reaches Success when the card provider accepts the order. There are no sandbox-only SKUs. The SKUs in this guide's samples are examples: before you run them, replace them with SKUs that your own catalog calls return in steps 1 and 3. A SKU that isn't in the catalog fails with SKU_NOT_FOUND every time, so you can use one to test a failed item.

#Next steps