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://test-gateway.mastercard.com/api/nvp/version/81 |
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"]}
subMerchant = OPTIONAL
subMerchant.identifier Alphanumeric + additional characters = COMPULSORY
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].replacementToken Alphanumeric = CONDITIONAL
- start using the replacement token instead of this token and
- delete this token
If a replacement token is provided, this token is not marked as invalid (status=INVALID) and has been updated to allow you to keep using it until you have started using the replacement token.
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
Cards: the card details entered directly or collected using a Point of Sale (POS) terminal.
Device payment methods such as Apple Pay, Android Pay, Samsung Pay or Google Pay.
Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout.
Card scheme tokens where the card was tokenized using a card scheme tokenization service such as Mastercard Digital Enablement Service (MDES).
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.directDebitCanada = CONDITIONAL
page.token[n].sourceOfFunds.provided.directDebitCanada.accountType Enumeration = CONDITIONAL
page.token[n].sourceOfFunds.provided.directDebitCanada.bankAccountHolder String = Always Provided
page.token[n].sourceOfFunds.provided.directDebitCanada.bankAccountNumber Alphanumeric + additional characters = Always Provided
page.token[n].sourceOfFunds.provided.directDebitCanada.financialInstitutionNumber Digits = Always Provided
page.token[n].sourceOfFunds.provided.directDebitCanada.transitNumber Digits = Always Provided
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.provided.paypal = CONDITIONAL
page.token[n].sourceOfFunds.provided.paypal.accountEmail Email = CONDITIONAL
page.token[n].sourceOfFunds.provided.paypal.accountHolder String = CONDITIONAL
page.token[n].sourceOfFunds.provided.paypal.billingAgreement = CONDITIONAL
page.token[n].sourceOfFunds.provided.paypal.billingAgreement.cardinality Enumeration = CONDITIONAL
page.token[n].sourceOfFunds.provided.paypal.billingAgreement.description String = CONDITIONAL
page.token[n].sourceOfFunds.provided.paypal.billingAgreement.id String = CONDITIONAL
page.token[n].sourceOfFunds.provided.paypal.billingAgreement.name String = CONDITIONAL
page.token[n].sourceOfFunds.provided.paypal.payerId String = CONDITIONAL
page.token[n].sourceOfFunds.type Enumeration = CONDITIONAL
page.token[n].status Enumeration = Always Provided
To change the token status, update the payment details stored against the token. Note that there are limitations on the update functionality depending on how your payment service provider has configured your token repository.
Card Details
A token that contains card details can become invalid in the following cases:
- Scheme Token Provider: If a response or notification from the scheme token provider indicates that the card number for this scheme token has changed and the scheme token is no longer active.
- Recurring Payment Advice: If the acquirer response for a recurring payment indicates that you must not attempt another recurring payment with the card number stored against this token.
- Account Updater: If you are configured for Account Updater and an Account Updater response indicates that the card details are no longer valid.
PayPal Details
A token that contains PayPal payment details becomes invalid when the payer withdraws their consent to the Billing Agreement.
page.token[n].subMerchant = CONDITIONAL
page.token[n].subMerchant.identifier Alphanumeric + additional characters = Always Provided
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