API reference

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

POST/API/v4/GiftCard/GetDigitalGiftCards

Returns 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

  • GetGiftCardsobjectRequired

    Wrapper object for the operation.

    Child parameters1
    • requestobjectRequired

      Wrapper object for the request fields. Lowercase request, as in the example.

      Child parameters2
      • IssuerAccountNumberstringRequired

        Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

      • CurrencystringRequired

        Three-letter ISO 4217 currency code used to filter the supported digital gift cards, for example USD or EUR.

Response fields

  • GetGiftCardResponseobject

    Wrapper object for the response.

    Child parameters1
    • GetGiftCardResultobject

      Result of the operation.

      Child parameters2
      • GiftCardobject[]

        List of supported digital gift card brands for the requested currency.

        Child parameters7
        • brandNamestring

          Merchant 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
          • Img80Wstring

            URL of the 80W image variant.

          • Img130wstring

            URL of the 130w image variant. Note the lowercase w, as in the example.

          • Img200Wstring

            URL of the 200W image variant.

          • Img300Wstring

            URL of the 300W image variant.

        • descriptionstring

          Detailed description of the gift card. Contains HTML markup in the example.

        • disclaimerstring

          Advisory notes, exceptions or cautions about the use or tracking of the gift card. Contains HTML markup in the example.

        • shortDescriptionstring

          Brief summary of the gift card. Contains HTML markup in the example.

        • termsstring

          Legal 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
          • skustring

            Unique Xtrm product code of the card. Pass it as SKU to UserWithdrawFund to transfer money to this card.

          • rewardNamestring

            Full product title of the gift card, for example Acme Retail Emporium Gift Card $25.00.

          • currencyCodestring

            Three-letter ISO 4217 currency code of the gift card.

          • statusstring

            Availability status of the gift card product, for example Active.

          • valueTypestring

            How the product is priced: FIXED_VALUE (a set denomination: the price is in faceValue, and minValue and maxValue are 0) or VARIABLE_VALUE (any amount from minValue to maxValue, with faceValue 0).

          • rewardTypestring

            System classification of the reward: gift card or donation in the gift card catalog.

          • maxValuenumber

            Maximum currency value the gift card can carry. Applies to variable-value products.

          • minValuenumber

            Minimum currency value the gift card can carry. Applies to variable-value products.

          • faceValuenumber

            Fixed 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.

      • OperationStatusobject

        Outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true) or failed (false).

        • Errorsstring[]

          Validation or execution error messages when the call fails. null on success, so decide with Success and use Errors only 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

POST/API/v4/GiftCard/GetGiftCardDetails

Returns 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

  • GetGiftCardsobjectRequired

    Wrapper object for the operation.

    Child parameters1
    • RequestobjectRequired

      Wrapper object for the request fields.

      Child parameters2
      • IssuerAccountNumberstringRequired

        Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

      • SKUstringRequired

        Unique stock keeping unit (SKU) identifier of the digital gift card product, for example a sku returned by GetDigitalGiftCards.

Response fields

  • GetGiftCardResponseobject

    Wrapper object for the response.

    Child parameters1
    • GetGiftCardDetailsResultobject

      Result of the operation.

      Child parameters2
      • GiftCardDetailobject

        The digital gift card brand that offers the requested SKU.

        Child parameters7
        • brandNamestring

          Merchant 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
          • Img80Wstring

            URL of the 80W image variant.

          • Img130wstring

            URL of the 130w image variant. Note the lowercase w, as in the example.

          • Img200Wstring

            URL of the 200W image variant.

          • Img300Wstring

            URL of the 300W image variant.

        • descriptionstring

          Detailed description of the gift card. Contains HTML markup in the example.

        • disclaimerstring

          Legal disclaimers, exceptions or cautions that apply to the gift card. Contains HTML markup in the example.

        • shortDescriptionstring

          Brief summary of the gift card. Contains HTML markup in the example.

        • termsstring

          Legal 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
          • skustring

            Unique Xtrm product code of the card. Matches the requested SKU.

          • rewardNamestring

            Full product title of the gift card, for example Acme Retail Emporium Gift Card $25.00.

          • currencyCodestring

            Three-letter ISO 4217 currency code of the gift card.

          • statusstring

            Availability status of the gift card product, for example Active.

          • valueTypestring

            How the product is priced: FIXED_VALUE (a set denomination: the price is in faceValue, and minValue and maxValue are 0) or VARIABLE_VALUE (any amount from minValue to maxValue, with faceValue 0).

          • rewardTypestring

            System classification of the reward: gift card or donation in the gift card catalog.

          • maxValuenumber

            Maximum currency value the gift card can carry. Applies to variable-value products.

          • minValuenumber

            Minimum currency value the gift card can carry. Applies to variable-value products.

          • faceValuenumber

            Fixed currency value of the gift card. Applies to fixed-value products.

      • OperationStatusobject

        Outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true) or failed (false).

        • Errorsstring[]

          Validation or execution error messages when the call fails. null on success, so decide with Success and use Errors only to explain a failure.

Related: List digital gift cards · Transfer from an individual recipient's wallet · Create a batch payment

#List prepaid cards

POST/API/v4/GiftCard/GetPrepaidCards

Returns 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

  • GetPrepaidCardsobjectRequired

    Wrapper object for the operation.

    Child parameters1
    • RequestobjectRequired

      Wrapper object for the request fields.

      Child parameters2
      • IssuerAccountNumberstringRequired

        Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

      • CurrencystringRequired

        Three-letter ISO 4217 currency code used to filter the supported prepaid cards, for example USD or EUR.

Response fields

  • GetPrepaidCardResponseobject

    Wrapper object for the response.

    Child parameters1
    • GetPrepaidCardResultobject

      Result of the operation.

      Child parameters2
      • GiftCardobject[]

        List of supported prepaid card brands for the requested currency. The array is named GiftCard although it holds prepaid cards.

        Child parameters7
        • brandNamestring

          Network 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
          • Img80Wstring

            URL of the 80W image variant.

          • Img130wstring

            URL of the 130w image variant. Note the lowercase w, as in the example.

          • Img200Wstring

            URL of the 200W image variant.

          • Img300Wstring

            URL of the 300W image variant.

        • descriptionstring

          Detailed description of the prepaid card. Contains HTML markup in the example.

        • disclaimerstring

          Legal disclaimers, exceptions or cautions that apply to the prepaid card. Contains HTML markup in the example.

        • shortDescriptionstring

          Brief summary of the prepaid card. Contains HTML markup in the example.

        • termsstring

          Legal 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
          • skustring

            Unique Xtrm product code of the card. Pass it as SKU to UserWithdrawFund to transfer money to this card.

          • rewardNamestring

            Full product title of the prepaid card, for example Visa® Prepaid Card USD.

          • currencyCodestring

            Three-letter ISO 4217 currency code of the prepaid card.

          • statusstring

            Availability status of the prepaid card product, for example Active.

          • valueTypestring

            How the product is priced: FIXED_VALUE (a set denomination: the price is in faceValue, and minValue and maxValue are 0) or VARIABLE_VALUE (any amount from minValue to maxValue, with faceValue 0).

          • rewardTypestring

            System classification of the reward: cash equivalent for prepaid cards.

          • maxValuenumber

            Maximum currency value the prepaid card can carry. Applies to variable-value products.

          • minValuenumber

            Minimum currency value the prepaid card can carry. Applies to variable-value products.

          • faceValuenumber

            Fixed 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.

      • OperationStatusobject

        Outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true) or failed (false).

        • Errorsstring[]

          Validation or execution error messages when the call fails. null on success, so decide with Success and use Errors only 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

POST/API/v4/GiftCard/GetPrepaidCardDetails

Returns 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

  • GetPrepaidCardsobjectRequired

    Wrapper object for the operation.

    Child parameters1
    • RequestobjectRequired

      Wrapper object for the request fields.

      Child parameters2
      • IssuerAccountNumberstringRequired

        Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

      • SKUstringRequired

        Unique stock keeping unit (SKU) identifier of the prepaid card product, for example a sku returned by GetPrepaidCards.

Response fields

  • GetPrepaidCardResponseobject

    Wrapper object for the response.

    Child parameters1
    • GetPrepaidCardDetailsResultobject

      Result of the operation.

      Child parameters2
      • PrepaidCardDetailobject

        The prepaid card brand that offers the requested SKU.

        Child parameters7
        • brandNamestring

          Brand 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
          • Img80Wstring

            URL of the 80W image variant.

          • Img130wstring

            URL of the 130w image variant. Note the lowercase w, as in the example.

          • Img200Wstring

            URL of the 200W image variant.

          • Img300Wstring

            URL of the 300W image variant.

        • descriptionstring

          Detailed description of the prepaid card. Contains HTML markup in the example.

        • disclaimerstring

          Legal disclaimers, exceptions or cautions that apply to the prepaid card. Contains HTML markup in the example.

        • shortDescriptionstring

          Brief summary of the prepaid card. Contains HTML markup in the example.

        • termsstring

          Legal 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
          • skustring

            Unique Xtrm product code of the card. Matches the requested SKU.

          • rewardNamestring

            Full product title of the prepaid card, for example Visa® Prepaid Card USD.

          • currencyCodestring

            Three-letter ISO 4217 currency code of the prepaid card.

          • statusstring

            Availability status of the prepaid card product, for example Active.

          • valueTypestring

            How the product is priced: FIXED_VALUE (a set denomination: the price is in faceValue, and minValue and maxValue are 0) or VARIABLE_VALUE (any amount from minValue to maxValue, with faceValue 0).

          • rewardTypestring

            System classification of the reward: cash equivalent for prepaid cards.

          • maxValuenumber

            Maximum currency value the prepaid card can carry. Applies to variable-value products.

          • minValuenumber

            Minimum currency value the prepaid card can carry. Applies to variable-value products.

          • faceValuenumber

            Fixed currency value of the prepaid card. Applies to fixed-value products.

      • OperationStatusobject

        Outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true) or failed (false).

        • Errorsstring[]

          Validation or execution error messages when the call fails. null on success, so decide with Success and use Errors only to explain a failure.

Related: List prepaid cards · Transfer from an individual recipient's wallet · Create a batch payment