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.
#Link a card to a recipient
/API/v4/Card/LinkCardLinks 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.
Important
You can link only US cards (CountryCode2 set to US), for either LinkCardType.
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
LinkCardobjectRequiredTop-level wrapper for the request.
Child parameters1
requestobjectRequiredThe link card request.
Child parameters5
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.UserIDstringRequiredThe Xtrm account number of the recipient whose card you link, starting with
SPNfor a company account orPATfor a personal account. It must be your own company or an account connected to it: any other account gets HTTP400withNot authorized to access this resource. Make One Time Password API Call to access this resource.LinkCardTypestringRequiredThe purpose of linking the card:
identityortransfer. Only atransfercard can receive Rapid Transfer payments (XTR94508).Allowed values:
identity,transfer.cardobjectRequiredThe card to link, with the cardholder's name and the card's billing address.
Child parameters14
FirstNamestringRequiredThe first name of the cardholder.
LastNamestringRequiredThe last name of the cardholder.
AddressLine1stringRequiredThe first line of the card's billing address.
CitystringRequiredThe city of the card's billing address.
CountryCode2stringRequiredThe two-character ISO country code of the card's billing address. Must be
US: Xtrm links only US cards.StatestringRequiredThe state or region abbreviation of the card's billing address, e.g.
"CA".PostalCodestringRequiredThe postal or ZIP code of the card's billing address.
NameOnCardstringRequiredThe full name exactly as it is printed on the card.
CardTypestringRequiredThe card brand:
Visa CardorMaster Card, or alsoAmex Cardfor anidentitycard.CardNostringRequiredThe full primary account number (PAN) of the credit or debit card, as a string.
ExpMonthstringRequiredThe expiration month of the card as a numeric string from
1to12, e.g."5".ExpYearstringRequiredThe four-digit expiration year of the card as a string, e.g.
"2030".cvvstringRequiredThe 3- or 4-digit card verification value (CVV/CVC), typically found on the back of the card, as a string.
AddressLine2stringOptionalThe second line of the card's billing address, such as an apartment or suite number.
EntityIDintegerOptionalAn internal Xtrm system identifier that maps this card profile to a specific entity record.
Response fields
LinkCardResponseobjectTop-level wrapper for the response.
Child parameters1
LinkCardResultobjectThe result of the
LinkCardcall.Child parameters4
CardTokenstringThe 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.
CardStatusstringThe status of the newly linked card.
LinkCardreturnsApproved, and you can use theCardTokenright away.AccountIdentityLevelstringThe identity level of the account in
UserID:Draft,Basic,StandardorAdvanced, from lowest to highest.OperationStatusobjectThe outcome of the call.
Child parameters2
Successbooleantrueif the operation succeeded, otherwisefalse.Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
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
/API/v4/Card/GetLinkedCardsReturns 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
GetLinkedCardAccountsobjectRequiredTop-level wrapper for the request. Note that the key is
GetLinkedCardAccounts, not the operation nameGetLinkedCards.Child parameters1
requestobjectRequiredThe get linked cards request.
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.useridstringRequiredThe Xtrm account number of the recipient whose linked cards you want, starting with
SPNfor a company account orPATfor a personal account. It must be your own company or an account connected to it: any other account gets HTTP400withNot authorized to access this resource. Make One Time Password API Call to access this resource.
Response fields
GetLinkedCardAccountsResponseobjectTop-level wrapper for the response.
Child parameters1
GetLinkedCardAccountsResultobjectThe result of the
GetLinkedCardscall.Child parameters2
CardDetailsobjectThe recipient's linked cards.
Child parameters1
Cardobject[]The list of linked cards.
Child parameters16
CardTokenstringThe token of the linked card: a 15-character string of digits and capital letters A to F.
FirstNamestringThe first name of the cardholder.
LastNamestringThe last name of the cardholder.
AddressLine1stringThe first line of the card's billing address.
AddressLine2stringThe second line of the card's billing address, such as an apartment or suite number.
CitystringThe city of the card's billing address.
StatestringThe state or region abbreviation of the card's billing address, e.g.
"MA".CountrystringThe country of the card's billing address. For an
identitycard, it's the two-character code the card was linked with (US). For atransfercard, 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".PostalCodestringThe postal or ZIP code of the card's billing address.
NameonCardstringThe full name exactly as it is printed on the card.
CardTypestringThe brand or network of the card, e.g.
"Visa"or"MasterCard".CardNostringThe masked card number, for example
"XXXXXX4444".ExpMonthstringThe expiration month of the card as a numeric string from
1to12, e.g."12".ExpYearstringThe four-digit expiration year of the card as a string, e.g.
"2029".LinkCardTypestringHow the card was linked:
identityortransfer, the valuesLinkCardaccepts.EntityIDintegerAn internal Xtrm system identifier that maps this card profile to a specific entity record.
OperationStatusobjectThe outcome of the call.
Child parameters2
Successbooleantrueif the operation succeeded, otherwisefalse.Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
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
/API/v4/Card/DeleteCardDeletes 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
DeleteCardobjectRequiredTop-level wrapper for the request.
Child parameters1
requestobjectRequiredThe delete card request.
Child parameters3
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.UserIDstringRequiredThe Xtrm account number of the recipient that owns the card, starting with
SPNfor a company account orPATfor a personal account. It must be your own company or an account connected to it: any other account gets HTTP400withNot authorized to access this resource. Make One Time Password API Call to access this resource.CardTokenstringRequiredThe unique tokenized identifier of the linked card to delete. Get it from
GetLinkedCards.
Response fields
DeleteCardobjectTop-level wrapper for the response.
Child parameters1
DeleteCardResultobjectThe result of the
DeleteCardcall.Child parameters2
CardTokenstringThe unique tokenized identifier of the card that was deleted.
OperationStatusobjectThe outcome of the call.
Child parameters2
Successbooleantrueif the operation succeeded, otherwisefalse.Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
Related: List a recipient's linked cards · Link a card to a recipient