Create or Update Token
Request for the gateway to store a payment instrument against a token, where you provide the token ID.
This may include:- credit or debit card details
- device payment details
- gift card details
- ACH bank account details
- Canadian Direct Debit bank account details
- PayPal billing agreement details
- The repository is configured for the Token Generation Strategy Preserve 6.4 and you attempt to change the account identifier (e.g. the card number or ACH account number). This would break the 6.4 preservation rule. Note that this rule is not enforced for PayPal Billing Agreement IDs.
- The repository is configured for the Token Management Strategy Unique Account Identifier and you attempt to update this token to an account identifier that is already assigned to another token and there. This would result in two tokens for the same account identifier, breaking the uniqueness rule.
If the repository is configured for scheme tokenization, the gateway will attempt to generate a scheme token for the stored card details.
If you want to tokenize card details associated to a previously successful payment, you can provide the order identifier of that payment using the field referenceOrderId. The order identifier provided in referenceOrderId must have card as the payment method, which includes both FPAN and DPAN based transactions. If it is the latter, the gateway won't attempt scheme tokenization even if you are enabled for scheme tokenization.
The gateway does not currently have support to store PayPal payment details against a gateway token.
However, you can- use this operation to store existing PayPal billing agreement details against a gateway token, for example, when migrating to the gateway.
- use the Create or Update Browser Payment Token operation to create or update a gateway token with PayPal billing agreement details.
If you provide a shipping address or shipping contact details, these will be ignored unless the token contains PayPal billing agreement details.
Note that the name on the card, billing address details, and customer details are only used by the gateway when submitting the tokenization request to the token service provider. These details are not stored against the gateway token.
If you tokenize card details provided by a payer via their issuer (i.e. push provisioning of scheme tokens), use this operation to supply the reference provided by the issuer for provisioning the scheme token. This reference will be used by the gateway to retrieve the scheme token and card details from the token service provider e.g. MDES.
URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/81/merchant/{merchantId}/token/{tokenid} |
HTTP Method | PUT |
Authentication |
This operation requires authentication via one of the following methods:
|
Request Parameters
session.id ASCII Text = OPTIONAL
billing = OPTIONAL
billing.address = OPTIONAL
billing.address.city String = OPTIONAL
billing.address.company String = OPTIONAL
billing.address.country Upper case alphabetic text = OPTIONAL
billing.address.postcodeZip Alphanumeric + additional characters = OPTIONAL
billing.address.stateProvince String = OPTIONAL
billing.address.stateProvinceCode String = OPTIONAL
billing.address.street String = OPTIONAL
billing.address.street2 String = OPTIONAL
correlationId String = OPTIONAL
customer = OPTIONAL
customer.email Email = OPTIONAL
customer.firstName String = OPTIONAL
customer.lastName String = OPTIONAL
customer.mobilePhone Telephone Number = OPTIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
customer.phone Telephone Number = OPTIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
customer.taxRegistrationId String = OPTIONAL
device = OPTIONAL
device.ipAddress String = OPTIONAL
IPv6 address will only be used in EMV 3DS authentication. Supplied IPv6 address will not be used for any other purposes.
referenceOrderId String = OPTIONAL
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.
responseControls = OPTIONAL
responseControls.sensitiveData String = OPTIONAL
session.id ASCII Text = OPTIONAL
session.version ASCII Text = OPTIONAL
To use optimistic locking, record session.version when you make your decisions, and then pass that value in session.version when you submit your request operation to the gateway.
If session.version provided by you does not match that stored against the session, the gateway will reject the operation with error.cause=INVALID_REQUEST.
See Making Business Decisions Based on Session Content.
shipping = OPTIONAL
shipping.address = OPTIONAL
shipping.address.city String = OPTIONAL
shipping.address.country Upper case alphabetic text = OPTIONAL
shipping.address.postcodeZip Alphanumeric + additional characters = OPTIONAL
shipping.address.stateProvince String = OPTIONAL
shipping.address.street String = OPTIONAL
shipping.address.street2 String = OPTIONAL
shipping.contact = OPTIONAL
shipping.contact.firstName String = OPTIONAL
shipping.contact.lastName String = OPTIONAL
shipping.origin.postcodeZip Alphanumeric + additional characters = OPTIONAL
sourceOfFunds = OPTIONAL
For card payments the source of funds information may be represented by combining one or more of the following: explicitly provided card details, a session identifier which the gateway will use to look up the card details and/or a card token. Precedence rules will be applied in that explicitly provided card details will override session card details which will override card token details. Each of these may represent partial card details, however the combination must result in a full and complete set of card details. See Using Multiple Sources of Card Details for examples.
posTerminal.serialNumber ASCII Text = OPTIONAL
sourceOfFunds.provided = OPTIONAL
sourceOfFunds.provided.ach = OPTIONAL
sourceOfFunds.provided.ach.accountType Enumeration = OPTIONAL
- 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).
sourceOfFunds.provided.ach.bankAccountHolder String = OPTIONAL
sourceOfFunds.provided.ach.bankAccountNumber Alphanumeric + additional characters = OPTIONAL
sourceOfFunds.provided.ach.routingNumber Digits = OPTIONAL
- Routing number,
- Transit number, or
- ABA number
Retrieve this information from the payer.
See also http://en.wikipedia.org/wiki/Routing_transit_number.
sourceOfFunds.provided.ach.secCode Enumeration = OPTIONAL
sourceOfFunds.provided.card = OPTIONAL
sourceOfFunds.provided.card.expiry = OPTIONAL
sourceOfFunds.provided.card.expiry.month Digits = COMPULSORY
sourceOfFunds.provided.card.expiry.year Digits = COMPULSORY
sourceOfFunds.provided.card.nameOnCard String = OPTIONAL
sourceOfFunds.provided.card.number Digits = OPTIONAL
sourceOfFunds.provided.card.securityCode Digits = OPTIONAL
sourceOfFunds.provided.directDebitCanada = OPTIONAL
sourceOfFunds.provided.directDebitCanada.accountType Enumeration = OPTIONAL
sourceOfFunds.provided.directDebitCanada.bankAccountHolder String = COMPULSORY
sourceOfFunds.provided.directDebitCanada.bankAccountNumber Alphanumeric + additional characters = COMPULSORY
sourceOfFunds.provided.directDebitCanada.financialInstitutionNumber Digits = COMPULSORY
sourceOfFunds.provided.directDebitCanada.transitNumber Digits = COMPULSORY
sourceOfFunds.provided.giftCard = OPTIONAL
sourceOfFunds.provided.giftCard.expectedLocalBrand String = OPTIONAL
sourceOfFunds.provided.giftCard.number Digits = OPTIONAL
sourceOfFunds.provided.giftCard.pin Digits = OPTIONAL
sourceOfFunds.provided.paypal = OPTIONAL
sourceOfFunds.provided.paypal.accountEmail Email = OPTIONAL
sourceOfFunds.provided.paypal.accountHolder String = OPTIONAL
sourceOfFunds.provided.paypal.billingAgreement = OPTIONAL
sourceOfFunds.provided.paypal.billingAgreement.cardinality Enumeration = COMPULSORY
sourceOfFunds.provided.paypal.billingAgreement.description String = OPTIONAL
sourceOfFunds.provided.paypal.billingAgreement.id String = COMPULSORY
sourceOfFunds.provided.paypal.billingAgreement.name String = OPTIONAL
sourceOfFunds.provided.paypal.payerId String = OPTIONAL
sourceOfFunds.provided.card.p2pe = OPTIONAL
sourceOfFunds.provided.card.p2pe.cardBin Digits = OPTIONAL
If you do not provided this, the gateway will not perform this check.
sourceOfFunds.provided.card.p2pe.encryptionState String = OPTIONAL
sourceOfFunds.provided.card.p2pe.initializationVector Hex = OPTIONAL
sourceOfFunds.provided.card.p2pe.keySerialNumber Hex = COMPULSORY
sourceOfFunds.provided.card.p2pe.payload Hex = COMPULSORY
sourceOfFunds.schemeTokenProvisioningIdentifier ASCII Text = OPTIONAL
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.
sourceOfFunds.token Alphanumeric = OPTIONAL
If account identifier details are also contained in the request, or the request contains a session with account identifier details, these take precedence over the details stored against the token.
sourceOfFunds.tokenRequestorID Alphanumeric = OPTIONAL
sourceOfFunds.type Enumeration = COMPULSORY
If you are making a payment with a gateway token, then you can leave this field unset, and only populate the sourceOfFunds.token field. However you can set this to CARD if you want to overwrite or augment the token data with a card security code, expiry date, or cardholder name.
subMerchant = OPTIONAL
subMerchant.identifier Alphanumeric + additional characters = COMPULSORY
transaction.currency Upper case alphabetic text = OPTIONAL
verificationStrategy Enumeration = OPTIONAL
- 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.
{merchantId} Alphanumeric + additional characters COMPULSORY
{tokenid} Alphanumeric COMPULSORY
- 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).
Response Parameters
result Enumeration = Always Provided
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.
billing = CONDITIONAL
billing.address = CONDITIONAL
billing.address.city String = CONDITIONAL
billing.address.company String = CONDITIONAL
billing.address.country Upper case alphabetic text = CONDITIONAL
billing.address.postcodeZip Alphanumeric + additional characters = CONDITIONAL
billing.address.stateProvince String = CONDITIONAL
billing.address.stateProvinceCode String = CONDITIONAL
billing.address.street String = CONDITIONAL
billing.address.street2 String = CONDITIONAL
correlationId String = CONDITIONAL
customer = CONDITIONAL
customer.email Email = CONDITIONAL
customer.firstName String = CONDITIONAL
customer.lastName String = CONDITIONAL
customer.mobilePhone String = CONDITIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
customer.phone String = CONDITIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
customer.taxRegistrationId String = CONDITIONAL
device = CONDITIONAL
IPv6 address will only be used in EMV 3DS authentication. Supplied IPv6 address will not be used for any other purposes.
device.ipAddress String = CONDITIONAL
IPv6 address will only be used in EMV 3DS authentication. Supplied IPv6 address will not be used for any other purposes.
referenceOrderId String = CONDITIONAL
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.
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.
repositoryId ASCII Text = CONDITIONAL
response.gatewayCode Enumeration = CONDITIONAL
result Enumeration = Always Provided
schemeToken = CONDITIONAL
schemeToken.provider Enumeration = CONDITIONAL
schemeToken.tokenIdentifier String = CONDITIONAL
shipping = CONDITIONAL
shipping.address = CONDITIONAL
shipping.address.city String = CONDITIONAL
shipping.address.country Upper case alphabetic text = CONDITIONAL
shipping.address.postcodeZip Alphanumeric + additional characters = CONDITIONAL
shipping.address.stateProvince String = CONDITIONAL
shipping.address.street String = CONDITIONAL
shipping.address.street2 String = CONDITIONAL
shipping.contact = CONDITIONAL
shipping.contact.firstName String = CONDITIONAL
shipping.contact.lastName String = CONDITIONAL
shipping.origin.postcodeZip Alphanumeric + additional characters = CONDITIONAL
sourceOfFunds = CONDITIONAL
sourceOfFunds.provided = Always Provided
sourceOfFunds.provided.ach = CONDITIONAL
sourceOfFunds.provided.ach.accountIdentifier String = CONDITIONAL
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).
sourceOfFunds.provided.ach.bankAccountHolder String = CONDITIONAL
sourceOfFunds.provided.ach.bankAccountNumber Digits = CONDITIONAL
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.
sourceOfFunds.provided.ach.secCode Enumeration = CONDITIONAL
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).
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.
sourceOfFunds.provided.card.deviceSpecificExpiry = CONDITIONAL
- • Device payments: the expiry date for the Device Primary Account Number (DPAN).
- • Digital wallets: the expiry date for the Token PAN.
sourceOfFunds.provided.card.deviceSpecificExpiry.month Digits = CONDITIONAL
sourceOfFunds.provided.card.deviceSpecificExpiry.year Digits = CONDITIONAL
sourceOfFunds.provided.card.deviceSpecificNumber Masked digits = CONDITIONAL
- • 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.
sourceOfFunds.provided.card.expiry Digits = Always Provided
sourceOfFunds.provided.card.fundingMethod Enumeration = Always Provided
sourceOfFunds.provided.card.issuer String = CONDITIONAL
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.
sourceOfFunds.provided.card.nameOnCard String = CONDITIONAL
sourceOfFunds.provided.card.number Masked digits = CONDITIONAL
sourceOfFunds.provided.card.scheme Enumeration = CONDITIONAL
sourceOfFunds.provided.directDebitCanada = CONDITIONAL
sourceOfFunds.provided.directDebitCanada.accountType Enumeration = CONDITIONAL
sourceOfFunds.provided.directDebitCanada.bankAccountHolder String = Always Provided
sourceOfFunds.provided.directDebitCanada.bankAccountNumber Alphanumeric + additional characters = Always Provided
sourceOfFunds.provided.directDebitCanada.financialInstitutionNumber Digits = Always Provided
sourceOfFunds.provided.directDebitCanada.transitNumber Digits = Always Provided
sourceOfFunds.provided.giftCard = CONDITIONAL
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.
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.
sourceOfFunds.provided.giftCard.number Masked digits = CONDITIONAL
sourceOfFunds.provided.giftCard.pin Masked digits = CONDITIONAL
sourceOfFunds.provided.giftCard.scheme Enumeration = CONDITIONAL
sourceOfFunds.provided.paypal = CONDITIONAL
sourceOfFunds.provided.paypal.accountEmail Email = CONDITIONAL
sourceOfFunds.provided.paypal.accountHolder String = CONDITIONAL
sourceOfFunds.provided.paypal.billingAgreement = CONDITIONAL
sourceOfFunds.provided.paypal.billingAgreement.cardinality Enumeration = CONDITIONAL
sourceOfFunds.provided.paypal.billingAgreement.description String = CONDITIONAL
sourceOfFunds.provided.paypal.billingAgreement.id String = CONDITIONAL
sourceOfFunds.provided.paypal.billingAgreement.name String = CONDITIONAL
sourceOfFunds.provided.paypal.payerId String = CONDITIONAL
sourceOfFunds.schemeTokenProvisioningIdentifier ASCII Text = CONDITIONAL
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.
sourceOfFunds.type Enumeration = CONDITIONAL
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.
subMerchant = CONDITIONAL
subMerchant.identifier Alphanumeric + additional characters = Always Provided
token Alphanumeric = CONDITIONAL
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.
usage = CONDITIONAL
usage.lastUpdated.merchantId Alphanumeric + additional characters = CONDITIONAL
usage.lastUpdated.time DateTime = CONDITIONAL
usage.lastUsedTime DateTime = CONDITIONAL
verificationStrategy Enumeration = CONDITIONAL
- 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.