Create or Update Token
Request for the gateway to store payment instrument (e.g. credit or debit cards, gift cards, ACH bank account details) against a token, where you provide the token id.
Note: The behaviour of this call depends on two aspects of your token repository configuration: Token Generation Strategy (either Merchant-Supplied, Random or Preserve 6.4) and Token Management strategy (Unique Card or Unique Token). For more information, see How to Configure Tokenization. Your Token Generation Strategy and Token Management Strategy are configured on your merchant profile (by your payment service provider). For all repository configurations, you can use this call to update the details stored against the token. If you use a Merchant-Supplied generation strategy, you also use this call to create the token. However, to maintain the repository rules, the gateway will reject your request and generate an error if:- 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.
- The repository is configured for the Token Management Strategy Unique Card Numberand 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 card number, breaking the uniqueness rule.
URL | https://paymentgateway.commbank.com.au/api/nvp/version/40 |
HTTP Method | POST |
Authentication |
This operation requires authentication via one of the following methods:
|
Request Parameters
apiOperation String =TOKENIZE FIXED
merchant Alphanumeric + additional characters = COMPULSORY
session.id ASCII Text = OPTIONAL
sourceOfFunds = COMPULSORY
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.
sourceOfFunds.token Alphanumeric = OPTIONAL
sourceOfFunds.type Enumeration = COMPULSORY
token Alphanumeric = COMPULSORY
apiOperation String =TOKENIZE FIXED
correlationId String = OPTIONAL
externalTokenProvider = OPTIONAL
externalTokenProvider.customData String = OPTIONAL
merchant Alphanumeric + additional characters = COMPULSORY
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.
sourceOfFunds = COMPULSORY
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.
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.number Digits = OPTIONAL
sourceOfFunds.provided.card.securityCode Digits = OPTIONAL
sourceOfFunds.provided.giftCard = OPTIONAL
sourceOfFunds.provided.giftCard.expectedLocalBrand String = OPTIONAL
sourceOfFunds.provided.giftCard.number Digits = OPTIONAL
sourceOfFunds.provided.giftCard.pin Digits = 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.token Alphanumeric = OPTIONAL
sourceOfFunds.type Enumeration = COMPULSORY
token Alphanumeric = COMPULSORY
transaction.currency Upper case alphabetic text = OPTIONAL
verificationStrategy Enumeration = OPTIONAL
Response Parameters
result Enumeration = Always Provided
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).
correlationId String = CONDITIONAL
externalTokenProvider = CONDITIONAL
externalTokenProvider.customData String = CONDITIONAL
externalTokenProvider.responseCode String = CONDITIONAL
externalTokenProvider.responseMessage String = CONDITIONAL
repositoryId ASCII Text = CONDITIONAL
response.gatewayCode Enumeration = CONDITIONAL
result Enumeration = Always Provided
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
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.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.number Masked digits = CONDITIONAL
sourceOfFunds.provided.card.scheme Enumeration = CONDITIONAL
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.type Enumeration = CONDITIONAL
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).
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