Gift cards & prepaid cards
Use these endpoints to look up the digital gift cards and prepaid cards that Xtrm supports: list the cards available in a currency, then get the details of one card from its SKU. The cards on offer vary by currency. Gift cards and prepaid cards are two more ways for an individual recipient to transfer money out of Xtrm.
Each card product has a unique SKU. To pay a card in a batch payment, send an item with SendMethodId XTR94505 for a digital gift card or XTR94503 for a prepaid card, the product's sku in Destination.SKU, and the email address that receives the card's digital credentials in Destination.Email. Both fields are required for these methods. When an individual recipient transfers money to a card, pass the SKU as SKU to UserWithdrawFund. In the GetPaymentMethods and GetUserPaymentMethods responses, these methods appear as XTR94505 (Digital Gift Cards) and XTR94503 (Prepaid Virtual Debit Card).
Every endpoint on this page is a POST call that takes your company's IssuerAccountNumber in the request body.
#List digital gift cards
/API/v4/GiftCard/GetDigitalGiftCardsReturns the digital gift cards that Xtrm supports in the currency you pass in Currency. A digital gift card is another way for an individual recipient to transfer money out, and the cards on offer vary by currency.
Each entry in GiftCard describes a brand (brandName, description, terms and so on) and lists its products in items. Each product has a unique sku, which you pass as the SKU input of a UserWithdrawFund call. Use valueType to tell fixed-value products, where faceValue applies, from variable-value products, where minValue and maxValue apply.
Tip
To pay a digital gift card in a batch payment, send an item with SendMethodId XTR94505, the product's sku in Destination.SKU, and the email address that receives the card's digital credentials in Destination.Email. Both fields are required for this method. When an individual recipient transfers money to a gift card, pass the product's sku as SKU to UserWithdrawFund, together with UserGiftCardEmailID, the email address the gift card details are sent to.
Body parameters
GetGiftCardsobjectRequiredWrapper object for the operation.
Child parameters1
requestobjectRequiredWrapper object for the request fields. Lowercase
request, as in the example.Child parameters2
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.CurrencystringRequiredThree-letter ISO 4217 currency code used to filter the supported digital gift cards, for example
USDorEUR.
Response fields
GetGiftCardResponseobjectWrapper object for the response.
Child parameters1
GetGiftCardResultobjectResult of the operation.
Child parameters2
GiftCardobject[]List of supported digital gift card brands for the requested currency.
Child parameters7
brandNamestringMerchant or brand name of the company that offers the gift card, for example
Acme Retail Emporium.imageUrlsobject[]Image URLs for the card brand. The example returns one object with four URL variants.
Child parameters4
Img80WstringURL of the
80Wimage variant.Img130wstringURL of the
130wimage variant. Note the lowercasew, as in the example.Img200WstringURL of the
200Wimage variant.Img300WstringURL of the
300Wimage variant.
descriptionstringDetailed description of the gift card. Contains HTML markup in the example.
disclaimerstringAdvisory notes, exceptions or cautions about the use or tracking of the gift card. Contains HTML markup in the example.
shortDescriptionstringBrief summary of the gift card. Contains HTML markup in the example.
termsstringLegal terms and usage conditions for redeeming and using the gift card. Contains HTML markup in the example.
itemsobject[]Products offered for this brand, one entry per SKU.
Child parameters10
skustringUnique Xtrm product code of the card. Pass it as
SKUtoUserWithdrawFundto transfer money to this card.rewardNamestringFull product title of the gift card, for example
Acme Retail Emporium Gift Card $25.00.currencyCodestringThree-letter ISO 4217 currency code of the gift card.
statusstringAvailability status of the gift card product, for example
Active.valueTypestringHow the product is priced:
FIXED_VALUE(a set denomination: the price is infaceValue, andminValueandmaxValueare0) orVARIABLE_VALUE(any amount fromminValuetomaxValue, withfaceValue0).rewardTypestringSystem classification of the reward:
gift cardordonationin the gift card catalog.maxValuenumberMaximum currency value the gift card can carry. Applies to variable-value products.
minValuenumberMinimum currency value the gift card can carry. Applies to variable-value products.
faceValuenumberFixed currency value of the gift card. Applies to fixed-value products.
countriesstring[]Two-letter ISO country codes of the countries that use the card's currency, for example
US.
OperationStatusobjectOutcome of the operation.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Validation or execution error messages when the call fails.
nullon success, so decide withSuccessand useErrorsonly to explain a failure.
Related: Get gift card details · Transfer from an individual recipient's wallet · Create a batch payment · List payment methods for individual recipients · List payment methods for paying recipients
#Get gift card details
/API/v4/GiftCard/GetGiftCardDetailsReturns detailed information about a digital gift card from its SKU. Use it to look up a card's brand information, terms and value rules, for example after you pick a sku from GetDigitalGiftCards and before you use it as the SKU input of a UserWithdrawFund call.
The response returns the brand in GiftCardDetail, with the product that matches the requested SKU in items. The product has no countries: GetDigitalGiftCards returns it on each product.
Body parameters
GetGiftCardsobjectRequiredWrapper object for the operation.
Child parameters1
RequestobjectRequiredWrapper object for the request fields.
Child parameters2
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.SKUstringRequiredUnique stock keeping unit (SKU) identifier of the digital gift card product, for example a
skureturned byGetDigitalGiftCards.
Response fields
GetGiftCardResponseobjectWrapper object for the response.
Child parameters1
GetGiftCardDetailsResultobjectResult of the operation.
Child parameters2
GiftCardDetailobjectThe digital gift card brand that offers the requested SKU.
Child parameters7
brandNamestringMerchant or brand name of the company that offers the gift card, for example
Acme Retail Emporium.imageUrlsobject[]Image URLs for the card brand. The example returns one object with four URL variants.
Child parameters4
Img80WstringURL of the
80Wimage variant.Img130wstringURL of the
130wimage variant. Note the lowercasew, as in the example.Img200WstringURL of the
200Wimage variant.Img300WstringURL of the
300Wimage variant.
descriptionstringDetailed description of the gift card. Contains HTML markup in the example.
disclaimerstringLegal disclaimers, exceptions or cautions that apply to the gift card. Contains HTML markup in the example.
shortDescriptionstringBrief summary of the gift card. Contains HTML markup in the example.
termsstringLegal terms and usage conditions for redeeming and using the gift card. Contains HTML markup in the example.
itemsobject[]Products of this brand. In the example, it holds the product that matches the requested
SKU.Child parameters9
skustringUnique Xtrm product code of the card. Matches the requested
SKU.rewardNamestringFull product title of the gift card, for example
Acme Retail Emporium Gift Card $25.00.currencyCodestringThree-letter ISO 4217 currency code of the gift card.
statusstringAvailability status of the gift card product, for example
Active.valueTypestringHow the product is priced:
FIXED_VALUE(a set denomination: the price is infaceValue, andminValueandmaxValueare0) orVARIABLE_VALUE(any amount fromminValuetomaxValue, withfaceValue0).rewardTypestringSystem classification of the reward:
gift cardordonationin the gift card catalog.maxValuenumberMaximum currency value the gift card can carry. Applies to variable-value products.
minValuenumberMinimum currency value the gift card can carry. Applies to variable-value products.
faceValuenumberFixed currency value of the gift card. Applies to fixed-value products.
OperationStatusobjectOutcome of the operation.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Validation or execution error messages when the call fails.
nullon success, so decide withSuccessand useErrorsonly to explain a failure.
Related: List digital gift cards · Transfer from an individual recipient's wallet · Create a batch payment
#List prepaid cards
/API/v4/GiftCard/GetPrepaidCardsReturns the prepaid cards that Xtrm supports in the currency you pass in Currency. A prepaid card is another way for an individual recipient to transfer money out, and the cards on offer vary by currency.
The response returns each card brand as an entry of an array named GiftCard, with its products in items. Each product has a unique sku, which you pass as the SKU input of a UserWithdrawFund call. Use valueType to tell fixed-value products, where faceValue applies, from variable-value products, where minValue and maxValue apply.
Tip
To pay a prepaid card in a batch payment, send an item with SendMethodId XTR94503, a product's sku from this list in Destination.SKU, and the email address that receives the card's digital credentials in Destination.Email. Both fields are required for this method. A prepaid card is the prepaid card for the batch currency: Xtrm checks the SKU and the amount against this list for that currency, and the current release orders the first prepaid card for the batch currency, at Amount (see Payment methods & destinations). When an individual recipient transfers money to a prepaid card, pass the product's sku as SKU to UserWithdrawFund. UserWithdrawFund also needs UserPrepaidVisaEmailID, the email address the prepaid card details are sent to.
Body parameters
GetPrepaidCardsobjectRequiredWrapper object for the operation.
Child parameters1
RequestobjectRequiredWrapper object for the request fields.
Child parameters2
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.CurrencystringRequiredThree-letter ISO 4217 currency code used to filter the supported prepaid cards, for example
USDorEUR.
Response fields
GetPrepaidCardResponseobjectWrapper object for the response.
Child parameters1
GetPrepaidCardResultobjectResult of the operation.
Child parameters2
GiftCardobject[]List of supported prepaid card brands for the requested currency. The array is named
GiftCardalthough it holds prepaid cards.Child parameters7
brandNamestringNetwork or company brand that offers the prepaid card, for example
Visa® Prepaid Card USD.imageUrlsobject[]Image URLs for the card brand. The example returns one object with four URL variants.
Child parameters4
Img80WstringURL of the
80Wimage variant.Img130wstringURL of the
130wimage variant. Note the lowercasew, as in the example.Img200WstringURL of the
200Wimage variant.Img300WstringURL of the
300Wimage variant.
descriptionstringDetailed description of the prepaid card. Contains HTML markup in the example.
disclaimerstringLegal disclaimers, exceptions or cautions that apply to the prepaid card. Contains HTML markup in the example.
shortDescriptionstringBrief summary of the prepaid card. Contains HTML markup in the example.
termsstringLegal terms and usage conditions for the distribution and use of the prepaid card. Contains HTML markup in the example.
itemsobject[]Products offered for this brand, one entry per SKU.
Child parameters10
skustringUnique Xtrm product code of the card. Pass it as
SKUtoUserWithdrawFundto transfer money to this card.rewardNamestringFull product title of the prepaid card, for example
Visa® Prepaid Card USD.currencyCodestringThree-letter ISO 4217 currency code of the prepaid card.
statusstringAvailability status of the prepaid card product, for example
Active.valueTypestringHow the product is priced:
FIXED_VALUE(a set denomination: the price is infaceValue, andminValueandmaxValueare0) orVARIABLE_VALUE(any amount fromminValuetomaxValue, withfaceValue0).rewardTypestringSystem classification of the reward:
cash equivalentfor prepaid cards.maxValuenumberMaximum currency value the prepaid card can carry. Applies to variable-value products.
minValuenumberMinimum currency value the prepaid card can carry. Applies to variable-value products.
faceValuenumberFixed currency value of the prepaid card. Applies to fixed-value products.
countriesstring[]Two-letter ISO country codes of the countries that use the card's currency, for example
US.
OperationStatusobjectOutcome of the operation.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Validation or execution error messages when the call fails.
nullon success, so decide withSuccessand useErrorsonly to explain a failure.
Related: Get prepaid card details · Transfer from an individual recipient's wallet · Create a batch payment · List payment methods for individual recipients · List payment methods for paying recipients
#Get prepaid card details
/API/v4/GiftCard/GetPrepaidCardDetailsReturns detailed information about a prepaid card from its SKU. Use it to look up a card's brand information, terms and value rules, for example after you pick a sku from GetPrepaidCards and before you use it as the SKU input of a UserWithdrawFund call.
The response returns the brand in PrepaidCardDetail, with the product that matches the requested SKU in items. The product has no countries: GetPrepaidCards returns it on each product.
Body parameters
GetPrepaidCardsobjectRequiredWrapper object for the operation.
Child parameters1
RequestobjectRequiredWrapper object for the request fields.
Child parameters2
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.SKUstringRequiredUnique stock keeping unit (SKU) identifier of the prepaid card product, for example a
skureturned byGetPrepaidCards.
Response fields
GetPrepaidCardResponseobjectWrapper object for the response.
Child parameters1
GetPrepaidCardDetailsResultobjectResult of the operation.
Child parameters2
PrepaidCardDetailobjectThe prepaid card brand that offers the requested SKU.
Child parameters7
brandNamestringBrand name of the company that issues the prepaid card, for example
Visa® Prepaid Card USD.imageUrlsobject[]Image URLs for the card brand. The example returns one object with four URL variants.
Child parameters4
Img80WstringURL of the
80Wimage variant.Img130wstringURL of the
130wimage variant. Note the lowercasew, as in the example.Img200WstringURL of the
200Wimage variant.Img300WstringURL of the
300Wimage variant.
descriptionstringDetailed description of the prepaid card. Contains HTML markup in the example.
disclaimerstringLegal disclaimers, exceptions or cautions that apply to the prepaid card. Contains HTML markup in the example.
shortDescriptionstringBrief summary of the prepaid card. Contains HTML markup in the example.
termsstringLegal terms and usage conditions for redeeming and using the prepaid card. Contains HTML markup in the example.
itemsobject[]Products of this brand. In the example, it holds the product that matches the requested
SKU.Child parameters9
skustringUnique Xtrm product code of the card. Matches the requested
SKU.rewardNamestringFull product title of the prepaid card, for example
Visa® Prepaid Card USD.currencyCodestringThree-letter ISO 4217 currency code of the prepaid card.
statusstringAvailability status of the prepaid card product, for example
Active.valueTypestringHow the product is priced:
FIXED_VALUE(a set denomination: the price is infaceValue, andminValueandmaxValueare0) orVARIABLE_VALUE(any amount fromminValuetomaxValue, withfaceValue0).rewardTypestringSystem classification of the reward:
cash equivalentfor prepaid cards.maxValuenumberMaximum currency value the prepaid card can carry. Applies to variable-value products.
minValuenumberMinimum currency value the prepaid card can carry. Applies to variable-value products.
faceValuenumberFixed currency value of the prepaid card. Applies to fixed-value products.
OperationStatusobjectOutcome of the operation.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Validation or execution error messages when the call fails.
nullon success, so decide withSuccessand useErrorsonly to explain a failure.
Related: List prepaid cards · Transfer from an individual recipient's wallet · Create a batch payment