Retrieve Token
Request to retrieve the payment details saved against the specified token.
URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/81/merchant/{merchantId}/token/{tokenid} |
HTTP Method | GET |
Authentication |
This operation requires authentication via one of the following methods:
|
Request Parameters
correlationId String = OPTIONAL
A transient identifier for the request, that can be used to match the response to the request.
The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100
responseControls = OPTIONAL
Container for fields that control the response returned for the request.
Fixed value
responseControls.sensitiveData String = OPTIONAL
Indicates how sensitive data is returned in the response.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50
subMerchant = OPTIONAL
Provide these parameters if you are a payment aggregator or facilitator and process payments on behalf of other merchants.
These merchants are referred to as your sub merchants.
The sub merchant's details you provide may be displayed on the payer's cardholder statement.
The gateway will use separate token repositories for each of your sub merchants
Fixed value
subMerchant.identifier Alphanumeric + additional characters = COMPULSORY
Your identifier for the sub-merchant.
Existence
COMPULSORY
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '.'
JSON type
String
minimum length
1
maximum length
100
{merchantId} Alphanumeric + additional characters COMPULSORY
The unique identifier issued to you by your payment provider.
Existence
COMPULSORY
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_'
XSD type
string
minimum length
1
maximum length
40
{tokenid} Alphanumeric COMPULSORY
On request, supply the token you wish to create or update.
You can only supply this value when creating a token if your token repository is configured to support merchant-supplied tokens.On response, the format of the token depends on the token generation strategy configured for your repository. See Tokenization for more details.You will receive a new token in field replacementToken when:
- Your token repository is configured to use a 6.4 Token Generation Strategy, and
- You set request.verificationStrategy = ACCOUNT_UPDATER or you are configured for the Token Maintenance Service functionality, and
- The Account Updater service provided a new account identifier (with a different 6.4 mask).
Existence
COMPULSORY
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
XSD type
string
minimum length
1
maximum length
40
Response Parameters
result Enumeration = Always Provided
A system-generated high level overall result of the transaction/operation.
Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
FAILURE
The operation was declined or rejected by the gateway, acquirer or issuer
PENDING
The operation is currently in progress or pending processing
SUCCESS
The operation was successfully processed
UNKNOWN
The result of the operation is unknown
status Enumeration = Always Provided
An indicator of whether or not you can use this token in transaction requests.
Transaction requests using an invalid token are rejected by the gateway.
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:
PayPal Details
A token that contains PayPal payment details becomes invalid when the payer withdraws their consent to the Billing Agreement.
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.
Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
INVALID
The payment details stored against the token have been identified as invalid. The gateway will reject operation payment requests using this token.
VALID
The payment details stored against the token are considered to be valid. The gateway will attempt to process operation requests using this token.
correlationId String = CONDITIONAL
A transient identifier for the request, that can be used to match the response to the request.
The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100
referenceOrderId String = CONDITIONAL
This is the reference to an order previously submitted by you to the gateway.
It is applicable to the following scenarios.
Tokenization requests:
Identifier for the order which will be used to generate a gateway token. The gateway will attempt tokenization of payment credentials linked to the order ID.
The order identifier provided in this field must be linked to a successfully processed order which has card (FPAN / DPAN) as the payment method.
When providing this field, you must not provide card details in the sourceOfFunds.provided.card parameter group, and you must set the sourceOfFunds.type field to CARD.
Payment transactions:
When submitting:
Tokenization requests:
Identifier for the order which will be used to generate a gateway token. The gateway will attempt tokenization of payment credentials linked to the order ID.
The order identifier provided in this field must be linked to a successfully processed order which has card (FPAN / DPAN) as the payment method.
When providing this field, you must not provide card details in the sourceOfFunds.provided.card parameter group, and you must set the sourceOfFunds.type field to CARD.
Payment transactions:
When submitting:
- an industry practice payment, this is the reference to the initial cardholder-initiated transaction.
- a resubmission transaction, this is the reference to the order which is being resubmitted.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40
replacementToken Alphanumeric = CONDITIONAL
If a replacement token for this token is provided, you must
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.
- 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.
However, you will no longer be able to update this token. For more details see Gateway Tokenization
Existence
CONDITIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
JSON type
String
minimum length
1
maximum length
40
repositoryId ASCII Text = CONDITIONAL
The unique identifier of the token repository associated with the merchant.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data consists of ASCII characters
JSON type
String
minimum length
1
maximum length
16
result Enumeration = Always Provided
A system-generated high level overall result of the transaction/operation.
Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
FAILURE
The operation was declined or rejected by the gateway, acquirer or issuer
PENDING
The operation is currently in progress or pending processing
SUCCESS
The operation was successfully processed
UNKNOWN
The result of the operation is unknown
schemeToken = CONDITIONAL
Where a scheme token is stored against this gateway token, this group contains details about the scheme token, such as the token service provider.
Fixed value
schemeToken.provider Enumeration = CONDITIONAL
The token service provider of a scheme token for the card details that are stored against the gateway token.
This field is returned once the token service provider can be identified. Note that it does not imply that a scheme token is available for use.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
AETS
American Express Token Service
MDES
Mastercard Digital Enablement Service
VTS
Visa Token Service
shipping = CONDITIONAL
Information on the shipping address including the contact details of the addressee.
Fixed value
shipping.address = CONDITIONAL
The address to which the goods contained in this order are being shipped.
This data may be used to qualify for better interchange rates on corporate purchase card transactions.
Fixed value
shipping.address.city String = CONDITIONAL
The city portion of the address.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100
shipping.address.country Upper case alphabetic text = CONDITIONAL
The 3 letter ISO standard alpha country code of the address.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
JSON type
String
minimum length
3
maximum length
3
shipping.address.postcodeZip Alphanumeric + additional characters = CONDITIONAL
The post code or zip code of the address.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'
JSON type
String
minimum length
1
maximum length
10
shipping.address.source Enumeration = CONDITIONAL
How you obtained the shipping address.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
ADDRESS_ON_FILE
Order shipped to an address that you have on file.
NEW_ADDRESS
Order shipped to an address provided by the payer for this transaction.
shipping.address.stateProvince String = CONDITIONAL
The state or province of the address.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
20
shipping.address.stateProvinceCode String = CONDITIONAL
The three character ISO 3166-2 country subdivision code for the state or province of the address.
Providing this field might improve your payer experience for 3-D Secure payer authentication.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
3
shipping.address.street String = CONDITIONAL
The first line of the address.
For example, this may be the street name and number, or the Post Office Box details.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100
shipping.address.street2 String = CONDITIONAL
The second line of the address (if provided).
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100
shipping.address.sameAsBilling Enumeration = CONDITIONAL
Indicates whether the shipping address provided is the same as the payer's billing address.
Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different.
The default value for this field is:
SAME - if the shipping and billing address are supplied, and all fields are the same (ignoring non-alphanumerics).
DIFFERENT - if the shipping and billing address are supplied, and at least one field is different (ignoring non-alphanumerics).
UNKNOWN - either shipping address or billing address is absent.
The default value for this field is:
SAME - if the shipping and billing address are supplied, and all fields are the same (ignoring non-alphanumerics).
DIFFERENT - if the shipping and billing address are supplied, and at least one field is different (ignoring non-alphanumerics).
UNKNOWN - either shipping address or billing address is absent.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
DIFFERENT
The shipping and billing addresses are different.
SAME
The shipping and billing addresses are the same.
UNKNOWN
It is not known if the shipping and billing addresses are the same.
shipping.contact = CONDITIONAL
Details of the contact person at the address the goods will be shipped to.
Fixed value
shipping.contact.firstName String = CONDITIONAL
The first name of the person to whom the order is being shipped.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50
shipping.contact.lastName String = CONDITIONAL
The last name or surname of the person to whom the order is being shipped.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50
sourceOfFunds = CONDITIONAL
Details about the source of the funds for this payment.
Fixed value
sourceOfFunds.provided = CONDITIONAL
The details of the source of funds when they are directly provided as opposed to via a token or session.
Fixed value
sourceOfFunds.provided.ach = CONDITIONAL
For ACH payments (sourceOfFunds.type=ACH) you must provide values for all fields within this parameter group, including details about the payers bank account as well as the type of ACH payment.
It is your responsibility to authenticate the payer and obtain authorization from the payer in accordance with the NACHA Operating Rules and Guidelines for the Standard Entry Class (SEC) associated with this payment. For details please refer to https://www.nacha.org/.
Fixed value
sourceOfFunds.provided.ach.accountIdentifier String = CONDITIONAL
The unique identifier of the routing number and bank account at the receiving financial institution.
Retrieve this information from the payer.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
19
maximum length
27
sourceOfFunds.provided.ach.accountType Enumeration = CONDITIONAL
An indicator identifying the type of bank account.
- 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).
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
CONSUMER_CHECKING
Consumer Checking Account
CONSUMER_SAVINGS
Consumer Savings Account
CORPORATE_CHECKING
Business Checking Account
sourceOfFunds.provided.ach.bankAccountHolder String = CONDITIONAL
The name of the bank account holder, as it appears on the account at the receiving financial institution.
Retrieve this information from the payer.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
28
sourceOfFunds.provided.ach.bankAccountNumber Digits = CONDITIONAL
The identifier of the bank account at the receiving financial institution.
Retrieve this information from the payer.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
JSON type
String
minimum length
9
maximum length
17
sourceOfFunds.provided.ach.routingNumber Digits = CONDITIONAL
The identifier of the receiving financial institution.
Also known as:
- Routing number,
- Transit number, or
- ABA number
Retrieve this information from the payer.
See also http://en.wikipedia.org/wiki/Routing_transit_number.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
JSON type
String
minimum length
9
maximum length
9
sourceOfFunds.provided.ach.secCode Enumeration = CONDITIONAL
Identifies the Standard Entry Class (SEC) code to be sent to the issuer.
The SEC is defined by NACHA and describes the origin and intent of the payment. For details please refer to https://www.nacha.org/.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
PPD
An ACH debit or credit payment (B2C) that has been authorized by an authenticated customer in written form (signed or similarly authenticated). PPD is used for pre-arranged payments (e.g. employee payroll, mortgage payments, expense reimbursement).
TEL
An ACH debit payment (B2C) that has been authorized by an authenticated customer via phone.
TEL may only be used if a relationship already exists between you and the consumer, or, the consumer initiates the contact with you.
WEB
An ACH debit payment (B2C) that has been authorized by an authenticated customer via the internet or a wireless network.
sourceOfFunds.provided.card = CONDITIONAL
Details about the card.
Use this parameter group when you have sourced payment details using:
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).
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).
Fixed value
sourceOfFunds.provided.card.brand Enumeration = Always Provided
The brand name used to describe the card that is recognized and accepted globally.
For many major card types this will match the scheme name. In some markets, a card may also be co-branded with a local brand that is recognized and accepted within its country/region of origin (see card.localBrand).
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.
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.
Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
AMEX
American Express
CHINA_UNIONPAY
China UnionPay
DINERS_CLUB
Diners Club
DISCOVER
Discover
JCB
JCB (Japan Credit Bureau)
LOCAL_BRAND_ONLY
The card does not have a global brand.
MAESTRO
Maestro
MASTERCARD
MasterCard
RUPAY
RuPay
UATP
UATP (Universal Air Travel Plan)
UNKNOWN
The brand of the card used in the transaction could not be identified
VISA
Visa
sourceOfFunds.provided.card.deviceSpecificExpiry = CONDITIONAL
The expiry date of the account number associated with a digital payment method.
The associated account number is returned in sourceOfFunds.provided.card.deviceSpecificNumber. This field is returned for:
- • Device payments: the expiry date for the Device Primary Account Number (DPAN).
- • Digital wallets: the expiry date for the Token PAN.
Fixed value
sourceOfFunds.provided.card.deviceSpecificExpiry.month Digits = CONDITIONAL
Month from the expiry date of the device specific account number.
Months are numbered January=1, through to December=12.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a number between 1 and 12 represented as a string.
JSON type
String
sourceOfFunds.provided.card.deviceSpecificExpiry.year Digits = CONDITIONAL
Year from the expiry date of the device specific account number.
The Common Era year is 2000 plus this value.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
JSON type
String
minimum length
2
maximum length
2
sourceOfFunds.provided.card.deviceSpecificNumber Masked digits = CONDITIONAL
The payer's account number associated with a digital payment method.
Use this field for:
- • Device payments: the payer's account number associated with the mobile device used for the payment. This is also known as the Device Primary Account Number (DPAN).
- • Digital wallets: the Token PAN returned by a digital wallet. The gateway only returns this value for Amex Express Checkout.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9, plus 'x' for masking
JSON type
String
minimum length
9
maximum length
19
sourceOfFunds.provided.card.expiry Digits = Always Provided
Expiry date as shown on the card in the format MMYY where months are numbered, so that for January MM=01, through to December MM=12 and the Common Era year is 2000 plus the value YY
Existence
Always Provided
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
JSON type
String
minimum length
4
maximum length
4
sourceOfFunds.provided.card.fundingMethod Enumeration = Always Provided
The method used by the payer to provide the funds for the payment.
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.
Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
CHARGE
The payer has a line of credit with the issuer which must be paid off monthly.
CREDIT
The payer has a revolving line of credit with the issuer.
DEBIT
Funds are immediately debited from the payer's account with the issuer.
UNKNOWN
The account funding method could not be determined.
sourceOfFunds.provided.card.issuer String = CONDITIONAL
The issuer of the card, if known.
WARNING: This information may be incorrect or incomplete – use at your own risk.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
0
maximum length
255
sourceOfFunds.provided.card.localBrand String = CONDITIONAL
The brand name used to describe a card that is recognized and accepted within its country/region of origin.
The card may also be co-branded with a brand name that is recognized and accepted globally (see card.brand).
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.
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.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
3
maximum length
50
sourceOfFunds.provided.card.nameOnCard String = CONDITIONAL
The cardholder's name as printed on the card.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
256
sourceOfFunds.provided.card.number Masked digits = CONDITIONAL
The account number embossed onto the card.
By default, the card number will be returned in 6.4 masking format, for example, 000000xxxxxx0000.If you wish to return unmasked card numbers, you must have the requisite permission, set responseControls.sensitiveData field to UNMASK, and authenticate your call to the API using certificate authentication.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9, plus 'x' for masking
JSON type
String
minimum length
9
maximum length
19
sourceOfFunds.provided.card.scheme Enumeration = CONDITIONAL
The organization that owns a card brand and defines operating regulations for its use.
The card scheme also controls authorization and settlement of card transactions among issuers and acquirers.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
AMEX
American Express
CHINA_UNIONPAY
China UnionPay
DINERS_CLUB
Diners Club
DISCOVER
Discover
JCB
JCB (Japan Credit Bureau)
MASTERCARD
MasterCard
OTHER
The scheme of the card used in the transaction could not be identified.
RUPAY
RuPay
UATP
UATP (Universal Air Travel Plan)
VISA
Visa
sourceOfFunds.provided.directDebitCanada = CONDITIONAL
For Direct Debit Canada payments (sourceOfFunds.type=DIRECT_DEBIT_CANADA) you must provide values for all fields within this parameter group, including details about the payers bank account as well as the type of Direct Debit Canada payment.
Fixed value
sourceOfFunds.provided.directDebitCanada.accountType Enumeration = CONDITIONAL
An indicator identifying the type of bank account.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
CONSUMER_CHECKING
Consumer Checking Account
CONSUMER_SAVINGS
Consumer Savings Account
sourceOfFunds.provided.directDebitCanada.bankAccountHolder String = Always Provided
The name of the bank account holder, as it appears on the account at the receiving financial institution.
Retrieve this information from the payer.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
28
sourceOfFunds.provided.directDebitCanada.bankAccountNumber Alphanumeric + additional characters = Always Provided
The identifier of the bank account at the receiving financial institution.
Retrieve this information from the payer.
Existence
Always Provided
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, ' ', '-', '/'
JSON type
String
minimum length
7
maximum length
12
sourceOfFunds.provided.directDebitCanada.financialInstitutionNumber Digits = Always Provided
The identifier of the receiving financial institution.
Existence
Always Provided
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
JSON type
String
minimum length
3
maximum length
3
sourceOfFunds.provided.directDebitCanada.transitNumber Digits = Always Provided
The transit number identifying the branch of the receiving financial institution where the bank account is held.
Existence
Always Provided
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
JSON type
String
minimum length
5
maximum length
5
sourceOfFunds.provided.giftCard = CONDITIONAL
Details as shown on the Gift Card.
Fixed value
sourceOfFunds.provided.giftCard.brand Enumeration = Always Provided
The brand name used to describe the card that is recognized and accepted globally.
For many major card types this will match the scheme name. In some markets, a card may also be co-branded with a local brand that is recognized and accepted within its country/region of origin (see card.localBrand).
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.
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.
Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
LOCAL_BRAND_ONLY
The card does not have a global brand.
sourceOfFunds.provided.giftCard.localBrand String = CONDITIONAL
The brand name used to describe a card that is recognized and accepted within its country/region of origin.
The card may also be co-branded with a brand name that is recognized and accepted globally (see card.brand).
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.
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.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50
sourceOfFunds.provided.giftCard.number Masked digits = CONDITIONAL
The account number embossed onto the card.
By default, the card number will be returned in 6.4 masking format, for example, 000000xxxxxx0000.If you wish to return unmasked card numbers, you must have the requisite permission, set responseControls.sensitiveData field to UNMASK, and authenticate your call to the API using certificate authentication.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9, plus 'x' for masking
JSON type
String
minimum length
9
maximum length
19
sourceOfFunds.provided.giftCard.pin Masked digits = CONDITIONAL
PIN number for the gift card.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9, plus 'x' for masking
JSON type
String
minimum length
4
maximum length
8
sourceOfFunds.provided.giftCard.scheme Enumeration = CONDITIONAL
The organization that owns a card brand and defines operating regulations for its use.
The card scheme also controls authorization and settlement of card transactions among issuers and acquirers.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
OTHER
The scheme of the card used in the transaction could not be identified.
sourceOfFunds.provided.paypal = CONDITIONAL
Information about the payer's PayPal account.
It is provided to you when the payer successfully makes a payment using PayPal or when you have established a billing agreement with the payer.
Fixed value
sourceOfFunds.provided.paypal.accountEmail Email = CONDITIONAL
The email address of the payer's PayPal account.
Existence
CONDITIONAL
Fixed value
Validation Rules
Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses
JSON type
String
sourceOfFunds.provided.paypal.accountHolder String = CONDITIONAL
The name of the account holder of the payer's PayPal account.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255
sourceOfFunds.provided.paypal.billingAgreement = CONDITIONAL
Details about the agreement you have established with the payer that allows you to bill the payer's PayPal account for goods or services.
Fixed value
sourceOfFunds.provided.paypal.billingAgreement.cardinality Enumeration = CONDITIONAL
Indicates the number of billing agreements between you and this payer.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
MULTIPLE
Indicates that you have multiple billing agreements with this payer. This means that a new agreement ID will be returned in response to each request.
SINGLE
Indicates that you have a single billing agreement with this payer. This means that the same agreement ID will be returned in response to each request.
sourceOfFunds.provided.paypal.billingAgreement.description String = CONDITIONAL
Your description for the PayPal billing agreement.
This description is displayed to the payer when they are asked to approve the billing agreement.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255
sourceOfFunds.provided.paypal.billingAgreement.id String = CONDITIONAL
An identifier provided by PayPal for the billing agreement.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100
sourceOfFunds.provided.paypal.billingAgreement.name String = CONDITIONAL
Your name for the PayPal billing agreement.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255
sourceOfFunds.provided.paypal.payerId String = CONDITIONAL
The unique identifier for the payer assigned by PayPal.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
13
sourceOfFunds.type Enumeration = CONDITIONAL
The payment method your payer has chosen for this payment.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
CARD
Use this value for payments that obtained the card details either directly from the card, or from a POS terminal, or from a wallet, or through a device payment method.
DIRECT_DEBIT_CANADA
The payer chose to pay using Direct Debit in Canada, also known as pre-authorized bank debits (PADs). You must provide the payer's bank account details in the sourceOfFunds.provided.directDebitCanada parameter group.
GIFT_CARD
The payer chose to pay using a gift card. The payer's gift card details must be provided under the sourceOfFunds.provided.giftCard parameter group.
PAYPAL
The payer selected the payment method PayPal.
status Enumeration = Always Provided
An indicator of whether or not you can use this token in transaction requests.
Transaction requests using an invalid token are rejected by the gateway.
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:
PayPal Details
A token that contains PayPal payment details becomes invalid when the payer withdraws their consent to the Billing Agreement.
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.
Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
INVALID
The payment details stored against the token have been identified as invalid. The gateway will reject operation payment requests using this token.
VALID
The payment details stored against the token are considered to be valid. The gateway will attempt to process operation requests using this token.
subMerchant = CONDITIONAL
Provide these parameters if you are a payment aggregator or facilitator and process payments on behalf of other merchants.
These merchants are referred to as your sub merchants.
The sub merchant's details you provide may be displayed on the payer's cardholder statement.
The gateway will use separate token repositories for each of your sub merchants
Fixed value
subMerchant.identifier Alphanumeric + additional characters = Always Provided
Your identifier for the sub-merchant.
Existence
Always Provided
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '.'
JSON type
String
minimum length
1
maximum length
100
token Alphanumeric = CONDITIONAL
On request, supply the token you wish to create or update.
You can only supply this value when creating a token if your token repository is configured to support merchant-supplied tokens.
On response, the format of the token depends on the token generation strategy configured for your repository. See Tokenization for more details.
You will receive a new token in field replacementToken when:
You should use the new token in future operation requests and delete the old token.
On response, the format of the token depends on the token generation strategy configured for your repository. See Tokenization for more details.
You will receive a new token in field replacementToken when:
- Your token repository is configured to use a 6.4 Token Generation Strategy, and
- You set request.verificationStrategy = ACCOUNT_UPDATER or you are configured for the Token Maintenance Service functionality, and
- The Account Updater service provided a new account identifier (with a different 6.4 mask).
You should use the new token in future operation requests and delete the old token.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
JSON type
String
minimum length
1
maximum length
40
usage = Always Provided
Information about the usage of the token.
Fixed value
usage.lastUpdated.merchantId Alphanumeric + additional characters = CONDITIONAL
If the token was last updated by a merchant this field contains the merchant ID of the merchant that made the update.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_'
JSON type
String
minimum length
1
maximum length
40
usage.lastUpdated.source Enumeration = CONDITIONAL
Indicates the source of the last update to the token.
Existence
CONDITIONAL
Fixed value
Validation Rules
Indicates the source of the last update to the token.
JSON type
String
Value must be a member of the following list. The values are case sensitive.
CLIENT
The token was last updated by a merchant submitting a Tokenize request. Field usage.lastUpdated.merchantId will contain the ID of the merchant that made the update.
GATEWAY
The token was last updated by the gateway as a result of the Account Updater or Token Maintenance Service functionality.
usage.lastUpdated.time DateTime = CONDITIONAL
The timestamp indicating the date and time the token was last updated.
Existence
CONDITIONAL
Fixed value
Validation Rules
An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"
JSON type
String
usage.lastUsedTime DateTime = CONDITIONAL
The timestamp indicating the date and time the token was last used or saved.
Existence
CONDITIONAL
Fixed value
Validation Rules
An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"
JSON type
String
verificationStrategy Enumeration = CONDITIONAL
The strategy used to verify the payment instrument details before they are stored.
You only need to specify the verification strategy if you want to override the default value configured for your merchant profile.
When the verification strategy is
- BASIC you must also provide the card expiry date in the sourceOfFunds.provided.card.expiry parameter group.
- ACQUIRER you must also provide the card expiry date in the sourceOfFunds.provided.card.expiry parameter group and the currency in the transaction.currency field.
- ACCOUNT_UPDATER you must also provide a currency in the transaction.currency field and the sourceOfFunds parameter group is optional.
- you need to be enabled for Account Updater by your payment service provider.
- you can subsequently inquire about any updates the gateway has made to the token based on the Account Updater response using the RETRIEVE_TOKEN or SEARCH_TOKENS operations.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
ACCOUNT_UPDATER
The gateway does not perform any validation or verification of the payment details provided, but schedules an Account Updater request to your acquirer to check for any updates to the payment details stored against the token. Once the Account Update request has been executed and indicates that the payment details have changed, the gateway automatically updates the payment details stored against the token or marks the token as invalid.
ACQUIRER
The gateway performs a Web Services API Verify request. Depending on the payment type, you may need to provide additional details to enable the submission of a Verify request.
BASIC
The gateway verifies the syntax and supported ranges of the payment instrument details provided, .e.g for a card it validates the card number format and checks if the card number falls within a valid BIN range.
NONE
The gateway does not perform any validation or verification of the payment instrument details provided.
error = CONDITIONAL
Information on possible error conditions that may occur while processing an operation using the API.
Fixed value
error.cause Enumeration = CONDITIONAL
Broadly categorizes the cause of the error.
For example, errors may occur due to invalid requests or internal system failures.
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
INVALID_REQUEST
The request was rejected because it did not conform to the API protocol.
REQUEST_REJECTED
The request was rejected due to security reasons such as firewall rules, expired certificate, etc.
SERVER_BUSY
The server did not have enough resources to process the request at the moment.
SERVER_FAILED
There was an internal system failure.
error.explanation String = CONDITIONAL
Textual description of the error based on the cause.
This field is returned only if the cause is INVALID_REQUEST or SERVER_BUSY.
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
1000
error.field String = CONDITIONAL
Indicates the name of the field that failed validation.
This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100
error.supportCode String = CONDITIONAL
Indicates the code that helps the support team to quickly identify the exact cause of the error.
This field is returned only if the cause is SERVER_FAILED or REQUEST_REJECTED.
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100
error.validationType Enumeration = CONDITIONAL
Indicates the type of field validation error.
This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
INVALID
The request contained a field with a value that did not pass validation.
MISSING
The request was missing a mandatory field.
UNSUPPORTED
The request contained a field that is unsupported.
result Enumeration = CONDITIONAL
A system-generated high level overall result of the operation.
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
ERROR
The operation resulted in an error and hence cannot be processed.