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 card | Prepaid card | |
|---|---|---|
SendMethodId | XTR94505 | XTR94503 |
| Browse the catalog | GetDigitalGiftCards | GetPrepaidCards |
| Check one SKU | GetGiftCardDetails | GetPrepaidCardDetails |
| Catalog request keys (list, details) | GetGiftCards › request, GetGiftCards › Request | GetPrepaidCards › Request for both |
Item Destination | Email and SKU, both required | Email and SKU, both required |
| Recipient | An individual recipient (PAT…) only; a business recipient fails with SENDMETHODID_NOT_FOUND | An individual recipient (PAT…) only; a business recipient fails with SENDMETHODID_NOT_FOUND |
rewardType in the catalog | gift card or donation | cash 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_TOKENenvironment variable. See Authentication and Sandbox & environments. - Your company's account number, the
SPNthat owns your API credentials (SPN1111222in the samples). You send it asIssuerAccountNumber. - A funded company wallet and its ID (
122181in the samples).GetCompanyWalletslists your wallets with theirWalletCurrencyandWalletBalance. 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
PATnumber, the individual recipient you reward (PAT1111002andPAT9999888in 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 withCheckUserExist, or create one withCreateUserfirst; 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
- Browse the gift card catalog
Call
GetDigitalGiftCardswith 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 lowercaserequest.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" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/GiftCard/GetDigitalGiftCards', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetGiftCards: { request: { IssuerAccountNumber: 'SPN1111222', Currency: 'USD', }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/GiftCard/GetDigitalGiftCards", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetGiftCards": { "request": { "IssuerAccountNumber": "SPN1111222", "Currency": "USD", }, }, }, ) print(response.status_code, response.text) response.raise_for_status()using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "GetGiftCards": { "request": { "IssuerAccountNumber": "SPN1111222", "Currency": "USD" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/GiftCard/GetDigitalGiftCards", new StringContent(json, Encoding.UTF8, "application/json")); var body = await response.Content.ReadAsStringAsync(); Console.WriteLine($"{(int)response.StatusCode} {body}"); response.EnsureSuccessStatusCode();import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "GetGiftCards": { "request": { "IssuerAccountNumber": "SPN1111222", "Currency": "USD" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/GiftCard/GetDigitalGiftCards")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/GiftCard/GetDigitalGiftCards'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetGiftCards' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'Currency' => 'USD', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));The response lists card brands in
GiftCard, each with display fields and its products initems, one persku. 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
valueTypeis one of two values, and it tells you which value fields apply:FIXED_VALUE: a set denomination. The price is infaceValue, andminValueandmaxValueare0.U935268is a 25 USD card.VARIABLE_VALUE: any amount fromminValuetomaxValue, andfaceValueis0.U935270takes 5 to 500 USD.
countrieslists 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 fromimageUrls(note the lowercasewinImg130w),shortDescriptionandterms. The text fields contain HTML in the example, so sanitize them before you render them.Keep for later: the
sku(U935268), andcountriesif you need it. - 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
GetGiftCardsagain, and this time the samples spell the inner keyRequest, with a capital R. Xtrm matches JSON property names in any case, sorequestworks 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" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/GiftCard/GetGiftCardDetails', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetGiftCards: { Request: { IssuerAccountNumber: 'SPN1111222', SKU: 'U935268', }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/GiftCard/GetGiftCardDetails", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetGiftCards": { "Request": { "IssuerAccountNumber": "SPN1111222", "SKU": "U935268", }, }, }, ) print(response.status_code, response.text) response.raise_for_status()using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "GetGiftCards": { "Request": { "IssuerAccountNumber": "SPN1111222", "SKU": "U935268" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/GiftCard/GetGiftCardDetails", new StringContent(json, Encoding.UTF8, "application/json")); var body = await response.Content.ReadAsStringAsync(); Console.WriteLine($"{(int)response.StatusCode} {body}"); response.EnsureSuccessStatusCode();import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "GetGiftCards": { "Request": { "IssuerAccountNumber": "SPN1111222", "SKU": "U935268" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/GiftCard/GetGiftCardDetails")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/GiftCard/GetGiftCardDetails'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetGiftCards' => [ 'Request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'SKU' => 'U935268', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));The brand comes back in
GiftCardDetail, with the matching product initems. The product has nocountries: take it from the catalog call if you need it. Abridged: the HTML text fields andimageUrlsare 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:
faceValuefor aFIXED_VALUEproduct, or a value fromminValuetomaxValuefor aVARIABLE_VALUEone. Also check thatcurrencyCodematches the currency of the wallet you'll pay from, and we recommend checking thatstatusisActive. During processing, before any money moves, a gift card in another currency fails withCURRENCY_MISMATCH, and an amount that doesn't fit the card fails withINVALID_CARD_AMOUNT, so validate both here.Keep for later: the
skuand the amount (25.00forU935268). - Find the prepaid card for your currency
Call
GetPrepaidCardswith the same currency. Here the root key isGetPrepaidCardsand the inner key isRequestwith 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" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/GiftCard/GetPrepaidCards', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetPrepaidCards: { Request: { IssuerAccountNumber: 'SPN1111222', Currency: 'USD', }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/GiftCard/GetPrepaidCards", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetPrepaidCards": { "Request": { "IssuerAccountNumber": "SPN1111222", "Currency": "USD", }, }, }, ) print(response.status_code, response.text) response.raise_for_status()using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "GetPrepaidCards": { "Request": { "IssuerAccountNumber": "SPN1111222", "Currency": "USD" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/GiftCard/GetPrepaidCards", new StringContent(json, Encoding.UTF8, "application/json")); var body = await response.Content.ReadAsStringAsync(); Console.WriteLine($"{(int)response.StatusCode} {body}"); response.EnsureSuccessStatusCode();import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "GetPrepaidCards": { "Request": { "IssuerAccountNumber": "SPN1111222", "Currency": "USD" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/GiftCard/GetPrepaidCards")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/GiftCard/GetPrepaidCards'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetPrepaidCards' => [ 'Request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'Currency' => 'USD', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));The prepaid card catalog lists the prepaid cards for the currency, in an array named
GiftCardwith 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 } } } }PREP9001is the USD prepaid card:VARIABLE_VALUE, from 5 to 1000 USD, with therewardTypecash equivalent. We recommend showing the brand'stermsanddisclaimerto the recipient.A prepaid card item must send this
skuinDestination.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, useGetPrepaidCardDetails.Keep for later: the
sku(PREP9001) and an amount in its range (100.00here). - 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:Field What 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, falseby default.trueemails 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 toDestination.Email.Items[].CustomerTransactionIdRequired. Your ID for this reward: Xtrm never generates one. Items[].RecipientIdThe individual recipient's PATnumber. A business recipient fails withSENDMETHODID_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[].SendMethodIdXTR94505for a gift card,XTR94503for 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 skufrom the catalog that matches the send method:U935268from step 1 for the gift card,PREP9001from step 3 for the prepaid card.This batch rewards John Smith (
PAT1111002) with the USD 25.00 gift cardU935268, 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 with422 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.Use your own unique IDs
CustomerBatchIdvalues are shared across all Xtrm accounts. Replace the sample IDs with your own unique values, for example ones that include your account number or a UUID, before you run this in the sandbox. Never have two requests for the sameCustomerBatchIdin flight at once.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" } } ] }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ 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', }, }, ], }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "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", }, }, ], }, ) print(response.status_code, response.text) response.raise_for_status()using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "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" } } ] } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer", new StringContent(json, Encoding.UTF8, "application/json")); var body = await response.Content.ReadAsStringAsync(); Console.WriteLine($"{(int)response.StatusCode} {body}"); response.EnsureSuccessStatusCode();import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "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" } } ] } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ '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', ], ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));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 inAccepted, not necessarily in request order, and the ones it refused inRejected. If no item passes, nothing is stored and the response is422, or409when an item already exists in this batch; see An item is rejected at submission. When both rewards pass, the response includes the following, with eachAmountechoed as a JSON number with the decimals you sent, so25and100come back as25.0and100.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": [] } }Acceptedonly 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. EachRejectedentry has theCustomerTransactionId, aKeysuch asINVALID_FIELD, theFieldthat failed, such asItems[0].Destination.SKU, and aMessage; see What can go wrong.Keep for later: the
CustomerBatchIdand, for each reward, itsCustomerTransactionIdand whether it was accepted or rejected. - Track the batch payment
Get the batch from the batch status endpoint, using your
CustomerBatchIdin the path. Sethistory=trueto include each item's processing attempts, and page through the items withrecordsToSkipandrecordsToTake.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"const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-REWARDS-0001?recordsToSkip=0&recordsToTake=50&history=true', { method: 'GET', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, }, }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.get( "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-REWARDS-0001?recordsToSkip=0&recordsToTake=50&history=true", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, ) print(response.status_code, response.text) response.raise_for_status()using System.Net.Http.Headers; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var response = await client.GetAsync("https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-REWARDS-0001?recordsToSkip=0&recordsToTake=50&history=true"); var body = await response.Content.ReadAsStringAsync(); Console.WriteLine($"{(int)response.StatusCode} {body}"); response.EnsureSuccessStatusCode();import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-REWARDS-0001?recordsToSkip=0&recordsToTake=50&history=true")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .GET() .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-REWARDS-0001?recordsToSkip=0&recordsToTake=50&history=true'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));The response returns the batch at the root, with no wrapper. Once Xtrm has processed both rewards, the
history=trueresponse 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:AcceptedorProcessinguntil the recipient's wallet is credited. This endpoint can also showVerified: the item passed validation and is waiting for the wallet credit.RetainedInWalletwhile Xtrm orders the card from the recipient's wallet, usually only briefly. Don't act on it while the batch is stillProcessing.Successwhen 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.Failedwhen the item failed before the card was ordered, for example withSKU_NOT_FOUNDorINVALID_CARD_AMOUNT. You can resubmit it after you fix the cause; see What can go wrong.- Still
RetainedInWalletonce 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 staysRetainedInWallet.
The batch is
Completedhere because every item isSuccess. While items are still being processed it readsProcessing, including while a card is being ordered, and when items fail it endsCompletedWithFailuresorFailed. Confirm each item'sStatusbefore you act on the batch's status; see Batch and payment statuses. Poll at a modest interval, or use webhooks. WhenPagination.HasMoreistrue, call again withrecordsToSkipset toPagination.NextRecordsToSkipto get the next page of items.Keep for later: each item's
Status,LastUpdatedAtand, for failed attempts, theErrorCode. - 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
CustomerBatchIdandCustomerTransactionIdin the path. Withhistory=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"const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-REWARDS-0001/Items/TXN-REWARDS-0002?history=true', { method: 'GET', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, }, }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.get( "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-REWARDS-0001/Items/TXN-REWARDS-0002?history=true", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, ) print(response.status_code, response.text) response.raise_for_status()using System.Net.Http.Headers; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var response = await client.GetAsync("https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-REWARDS-0001/Items/TXN-REWARDS-0002?history=true"); var body = await response.Content.ReadAsStringAsync(); Console.WriteLine($"{(int)response.StatusCode} {body}"); response.EnsureSuccessStatusCode();import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-REWARDS-0001/Items/TXN-REWARDS-0002?history=true")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .GET() .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-REWARDS-0001/Items/TXN-REWARDS-0002?history=true'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));The sample checks Jane Doe's prepaid card,
TXN-REWARDS-0002. Here is itshistory=trueresponse: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" } ] }DeliveryTypeis set once an item isSuccess:Prepaid Virtual Debit Cardfor a prepaid card (XTR94503), as here, andDigital Gift Cardsfor a gift card (XTR94505). ARetainedInWalletitem reportsWallet, both while the card is being ordered and after the order has failed, and anAccepted,ProcessingorFaileditem an empty string.Attemptslists each try, oldest first; this reward succeeded on its first attempt. This endpoint repeats the item's own times in every attempt'sCreatedAtandCompletedAt, so order attempts byAttemptNo. A successful card item can also show twoSuccessattempts with the sameAttemptNo: treat them as one outcome.Keep for your records: the item's final
Status,DeliveryTypeandLastUpdatedAt, 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
How Xtrm validates, processes and delivers each payment in a batch, wallet first.
Create a batch paymentMix card rewards with bank, wallet, check and Rapid Transfer items in one batch.
Pay individual recipientsFind or create the individual recipients you reward, and pay them in a batch.
Batch and payment statusesWhat each batch, payment and attempt status means.
WebhooksReceive and verify batch payment events as your rewards are processed.
Gift cards & prepaid cards referenceEvery field of the four catalog endpoints, with full examples.