Search Tokens
Request to find token records that match the query. If the token records span across pages, you can limit the results returned per page and retrieve the next set of results using subsequent requests.
URL | https://eu-gateway.mastercard.com/api/nvp/version/39 |
HTTP Method | POST |
Authentication |
This operation requires authentication via one of the following methods:
|
Request Parameters
apiOperation String =SEARCH_TOKENS FIXED
merchant Alphanumeric + additional characters = COMPULSORY
apiOperation String =SEARCH_TOKENS FIXED
correlationId String = OPTIONAL
limit Integer = OPTIONAL
merchant Alphanumeric + additional characters = COMPULSORY
nextPage String = OPTIONAL
query String = OPTIONAL
The syntax for token queries supports:
- Operators: EQ
- Fields: sourceOfFunds.provided.card.number, sourceOfFunds.provided.giftCard.number, sourceOfFunds.provided.ach.accountIdentifier, token, sourceOfFunds.provided.card.expiry
- Operators: GT
- Fields: usage.lastUpdated
- Operators: LE
- Fields: sourceOfFunds.provided.card.expiry
Examples:
- Search for token:
{"EQ":["token","GD1209-0160 0149 0098 6248"]}
- Search for card:
{"EQ":["sourceOfFunds.provided.card.number","4111111111111111"]}
- Search for gift card:
{"EQ":["sourceOfFunds.provided.giftCard.number","4111111111111111"]}
- Search for ACH payment details:
{"EQ":["sourceOfFunds.provided.ach.accountIdentifier","123123123/1234567890123456"]}
- Search for card expiry(MMYY):
{"EQ":["sourceOfFunds.provided.card.expiry","0517"]}
{"LE":["sourceOfFunds.provided.card.expiry","0517"]}
- Search for updated tokens:
{"GT":["usage.lastUpdated","2014-10-31T03:11:53Z"]}
Response Parameters
result Enumeration = Always Provided
correlationId String = CONDITIONAL
nextPage String = CONDITIONAL
This field will be absent if the gateway has no more results to return.
page = CONDITIONAL
page.token[n] = CONDITIONAL
page.token[n].repositoryId ASCII Text = CONDITIONAL
page.token[n].sourceOfFunds = CONDITIONAL
page.token[n].sourceOfFunds.provided = CONDITIONAL
page.token[n].sourceOfFunds.provided.ach = CONDITIONAL
page.token[n].sourceOfFunds.provided.ach.accountIdentifier String = CONDITIONAL
page.token[n].sourceOfFunds.provided.ach.accountType Enumeration = CONDITIONAL
- Consumer (checking or savings), or
- Business
For pre-arranged payments (sourceOfFunds.provided.ach.secCode=PPD) retrieve this information from the payer.
If payments were telephone-initiated (sourceOfFunds.provided.ach.secCode=TEL) or internet-initiated (sourceOfFunds.provided.ach.secCode=WEB) you may choose to limit the payer's options (e.g. only support consumer checking accounts), depending on your type of business (e.g. B2C online webshop).
page.token[n].sourceOfFunds.provided.ach.bankAccountHolder String = CONDITIONAL
page.token[n].sourceOfFunds.provided.ach.bankAccountNumber Digits = CONDITIONAL
page.token[n].sourceOfFunds.provided.ach.routingNumber Digits = CONDITIONAL
- Routing number,
- Transit number, or
- ABA number
Retrieve this information from the payer.
See also http://en.wikipedia.org/wiki/Routing_transit_number.
page.token[n].sourceOfFunds.provided.ach.secCode Enumeration = CONDITIONAL
page.token[n].sourceOfFunds.provided.card = CONDITIONAL
page.token[n].sourceOfFunds.provided.card.brand Enumeration = Always Provided
You may use this information to support surcharging decisions. This information is gathered from 3rd party sources and may not be accurate in all circumstances.
page.token[n].sourceOfFunds.provided.card.expiry Digits = Always Provided
page.token[n].sourceOfFunds.provided.card.fundingMethod Enumeration = Always Provided
page.token[n].sourceOfFunds.provided.card.localBrand String = CONDITIONAL
You may use this information to support surcharging decisions. This information is gathered from 3rd party sources and may not be accurate in all circumstances.
page.token[n].sourceOfFunds.provided.card.number Masked digits = CONDITIONAL
If you authenticated using certificate authentication, then your masking settings will be used. This allows you to return unmasked card numbers if you have chosen not to apply masking.
If you authenticated to the API by a means other than certificate authentication, then the card number will be returned with your masking settings or 6.4; whichever is more restrictive for example, 000000xxxxxx0000.
page.token[n].sourceOfFunds.provided.card.scheme Enumeration = CONDITIONAL
page.token[n].sourceOfFunds.provided.giftCard = CONDITIONAL
page.token[n].sourceOfFunds.provided.giftCard.brand Enumeration = Always Provided
You may use this information to support surcharging decisions. This information is gathered from 3rd party sources and may not be accurate in all circumstances.
page.token[n].sourceOfFunds.provided.giftCard.localBrand String = CONDITIONAL
You may use this information to support surcharging decisions. This information is gathered from 3rd party sources and may not be accurate in all circumstances.
page.token[n].sourceOfFunds.provided.giftCard.number Masked digits = CONDITIONAL
page.token[n].sourceOfFunds.provided.giftCard.pin Masked digits = CONDITIONAL
page.token[n].sourceOfFunds.provided.giftCard.scheme Enumeration = CONDITIONAL
page.token[n].sourceOfFunds.type Enumeration = CONDITIONAL
page.token[n].status Enumeration = Always Provided
You can clear an invalid status by updating the card details stored against the token.
To use the Account Updater functionality you must sign up for this feature with your acquirer and ask your payment service provider to enable Account Updater on our merchant acquirer link(s).
page.token[n].token Alphanumeric = CONDITIONAL
- RANDOM_WITH_LUHN: Token is 16 digits long, starts with 9, and is in the format of 9nnnnnnnnnnnnnnC, where n represents any number, and C represents a check digit such that the token will conform to the Luhn algorithm.
- PRESERVE_6_4: The first 6 and last 4 digits of the token are the same as the first 6 and last 4 digits of the provided card number, middle digits are randomized, the token id does NOT conform to Luhn algorithm.
- MERCHANT_PROVIDED: The merchant must supply the token id in the Save request