API reference

Cards

Link credit or debit cards to a recipient's Xtrm account, list the linked cards, and delete them. A recipient is identified by its Xtrm account number: SPN… for a business recipient or PAT… for an individual recipient. Linked cards let you make pass-through payments straight to a recipient's card.

When you link a card, you set its LinkCardType to identity or transfer. Only US cards can be linked, whatever the LinkCardType.

Xtrm returns a CardToken for each linked card: a 15-character string of digits and capital letters A to F, such as EC1B22028C5B488. Store it as a string, exactly as returned. GetLinkedCards lists the tokens, and DeleteCard needs one. To pay a card in a batch payment, send a Rapid Transfer item (SendMethodId XTR94508) with the token in Destination.CardToken. UserWithdrawFund and FundCompanyWalletUsingCreditCard also take the token as CardToken.

POST/API/v4/Card/LinkCard

Links a credit or debit card to a recipient's Xtrm account (UserID). Set LinkCardType to identity or transfer to say what the card is for.

Pass the cardholder's name, the card details (including the full card number in CardNo and the cvv) and the card's billing address in the card object. Pass EntityID to map the card profile to a specific entity record.

On success, the response returns the CardToken that Xtrm generates for the card, the card's status (CardStatus) and the compliance verification level of the account's identity (AccountIdentityLevel). Use the CardToken to refer to the card in later calls, such as DeleteCard.

Note

Only identity cards can fund a wallet with FundCompanyWalletUsingCreditCard.

Note

An account can have up to 3 linked cards. Past that, LinkCard refuses the link with You can link maximum 3 Cards. Funding a wallet with card details instead of a CardToken also links the card, so it counts toward the same limit.

Tip

In the sandbox, link cards with a standard test number: Visa 4111111111111111 or Mastercard 5555555555554444, with a future expiry date and a three-digit CVV. Never use real card data in the sandbox.

Note

In the example, the cardholder, card and billing address fields are nested in a lowercase card object, while IssuerAccountNumber, UserID, LinkCardType and EntityID sit directly in request.

Body parameters

  • LinkCardobjectRequired

    Top-level wrapper for the request.

    Child parameters1
    • requestobjectRequired

      The link card request.

      Child parameters5
      • 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.

      • UserIDstringRequired

        The Xtrm account number of the recipient whose card you link, starting with SPN for a company account or PAT for a personal account. It must be your own company or an account connected to it: any other account gets HTTP 400 with Not authorized to access this resource. Make One Time Password API Call to access this resource.

      • LinkCardTypestringRequired

        The purpose of linking the card: identity or transfer. Only a transfer card can receive Rapid Transfer payments (XTR94508).

        Allowed values: identity, transfer.

      • cardobjectRequired

        The card to link, with the cardholder's name and the card's billing address.

        Child parameters14
        • FirstNamestringRequired

          The first name of the cardholder.

        • LastNamestringRequired

          The last name of the cardholder.

        • AddressLine1stringRequired

          The first line of the card's billing address.

        • CitystringRequired

          The city of the card's billing address.

        • CountryCode2stringRequired

          The two-character ISO country code of the card's billing address. Must be US: Xtrm links only US cards.

        • StatestringRequired

          The state or region abbreviation of the card's billing address, e.g. "CA".

        • PostalCodestringRequired

          The postal or ZIP code of the card's billing address.

        • NameOnCardstringRequired

          The full name exactly as it is printed on the card.

        • CardTypestringRequired

          The card brand: Visa Card or Master Card, or also Amex Card for an identity card.

        • CardNostringRequired

          The full primary account number (PAN) of the credit or debit card, as a string.

        • ExpMonthstringRequired

          The expiration month of the card as a numeric string from 1 to 12, e.g. "5".

        • ExpYearstringRequired

          The four-digit expiration year of the card as a string, e.g. "2030".

        • cvvstringRequired

          The 3- or 4-digit card verification value (CVV/CVC), typically found on the back of the card, as a string.

        • AddressLine2stringOptional

          The second line of the card's billing address, such as an apartment or suite number.

      • EntityIDintegerOptional

        An internal Xtrm system identifier that maps this card profile to a specific entity record.

Response fields

  • LinkCardResponseobject

    Top-level wrapper for the response.

    Child parameters1
    • LinkCardResultobject

      The result of the LinkCard call.

      Child parameters4
      • CardTokenstring

        The token Xtrm generates for the linked card: a 15-character string of digits and capital letters A to F. Store it as a string, exactly as returned.

      • CardStatusstring

        The status of the newly linked card. LinkCard returns Approved, and you can use the CardToken right away.

      • AccountIdentityLevelstring

        The identity level of the account in UserID: Draft, Basic, Standard or Advanced, from lowest to highest.

      • OperationStatusobject

        The outcome of the call.

        Child parameters2
        • Successboolean

          true if the operation succeeded, otherwise false.

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

Related: List a recipient's linked cards · Delete a linked card · Transfer from an individual recipient's wallet · Transfer from a business recipient's wallet · Create a batch payment · Fund a wallet with a credit card

#List a recipient's linked cards

POST/API/v4/Card/GetLinkedCards

Returns the cards linked to a recipient's Xtrm account (userid). Use it when you pay straight to a recipient's card, and to get the CardToken that other calls, such as DeleteCard, need.

Each entry in CardDetails.Card includes the card's CardToken, the cardholder's name and billing address, the card brand (CardType), a masked card number (CardNo), the expiration month and year, the LinkCardType and the EntityID.

Note

The request wrapper key is GetLinkedCardAccounts (not GetLinkedCards), and the recipient field is lowercase userid, unlike UserID in LinkCard and DeleteCard.

Body parameters

  • GetLinkedCardAccountsobjectRequired

    Top-level wrapper for the request. Note that the key is GetLinkedCardAccounts, not the operation name GetLinkedCards.

    Child parameters1
    • requestobjectRequired

      The get linked cards request.

      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.

      • useridstringRequired

        The Xtrm account number of the recipient whose linked cards you want, starting with SPN for a company account or PAT for a personal account. It must be your own company or an account connected to it: any other account gets HTTP 400 with Not authorized to access this resource. Make One Time Password API Call to access this resource.

Response fields

  • GetLinkedCardAccountsResponseobject

    Top-level wrapper for the response.

    Child parameters1
    • GetLinkedCardAccountsResultobject

      The result of the GetLinkedCards call.

      Child parameters2
      • CardDetailsobject

        The recipient's linked cards.

        Child parameters1
        • Cardobject[]

          The list of linked cards.

          Child parameters16
          • CardTokenstring

            The token of the linked card: a 15-character string of digits and capital letters A to F.

          • FirstNamestring

            The first name of the cardholder.

          • LastNamestring

            The last name of the cardholder.

          • AddressLine1string

            The first line of the card's billing address.

          • AddressLine2string

            The second line of the card's billing address, such as an apartment or suite number.

          • Citystring

            The city of the card's billing address.

          • Statestring

            The state or region abbreviation of the card's billing address, e.g. "MA".

          • Countrystring

            The country of the card's billing address. For an identity card, it's the two-character code the card was linked with (US). For a transfer card, Xtrm takes the country, name and address from the account holder's profile, with the country as a full name such as "United States of America".

          • PostalCodestring

            The postal or ZIP code of the card's billing address.

          • NameonCardstring

            The full name exactly as it is printed on the card.

          • CardTypestring

            The brand or network of the card, e.g. "Visa" or "MasterCard".

          • CardNostring

            The masked card number, for example "XXXXXX4444".

          • ExpMonthstring

            The expiration month of the card as a numeric string from 1 to 12, e.g. "12".

          • ExpYearstring

            The four-digit expiration year of the card as a string, e.g. "2029".

          • LinkCardTypestring

            How the card was linked: identity or transfer, the values LinkCard accepts.

          • EntityIDinteger

            An internal Xtrm system identifier that maps this card profile to a specific entity record.

      • OperationStatusobject

        The outcome of the call.

        Child parameters2
        • Successboolean

          true if the operation succeeded, otherwise false.

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

Related: Link a card to a recipient · Delete a linked card · Transfer from an individual recipient's wallet · Transfer from a business recipient's wallet · Create a batch payment · Fund a wallet with a credit card

#Delete a linked card

POST/API/v4/Card/DeleteCard

Deletes a card linked to a recipient's Xtrm account (UserID). Identify the card by its CardToken, which you get from GetLinkedCards.

On success, the response returns the CardToken of the deleted card.

Body parameters

  • DeleteCardobjectRequired

    Top-level wrapper for the request.

    Child parameters1
    • requestobjectRequired

      The delete card request.

      Child parameters3
      • 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.

      • UserIDstringRequired

        The Xtrm account number of the recipient that owns the card, starting with SPN for a company account or PAT for a personal account. It must be your own company or an account connected to it: any other account gets HTTP 400 with Not authorized to access this resource. Make One Time Password API Call to access this resource.

      • CardTokenstringRequired

        The unique tokenized identifier of the linked card to delete. Get it from GetLinkedCards.

Response fields

  • DeleteCardobject

    Top-level wrapper for the response.

    Child parameters1
    • DeleteCardResultobject

      The result of the DeleteCard call.

      Child parameters2
      • CardTokenstring

        The unique tokenized identifier of the card that was deleted.

      • OperationStatusobject

        The outcome of the call.

        Child parameters2
        • Successboolean

          true if the operation succeeded, otherwise false.

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

Related: List a recipient's linked cards · Link a card to a recipient