Create or Update Token (with system-generated 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 the system generates 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).

If you are configured to use the Token Generation Strategy Random or Preserve 6.4', you can use this call to create the token. If you use the Token Generation Strategy Merchant-Supplied, do not use this call but use the Tokenize call instead.

Typically, this call will return a new token. However, if the repository is configured for the Token Management Strategy Unique Card Number and the supplied card number has previously been stored against an existing token, the gateway will return that token.

POST https://anzegate.gateway.mastercard.com/api/rest/version/45 / merchant / {merchantId} / token

Authentication

This operation requires authentication via one of the following methods:


  • Certificate authentication.
  • Basic HTTP authentication as described at w3.org. Provide 'merchant.<your gateway merchant ID>' in the userid portion and your API password in the password portion.

Request

URL Parameters

{merchantId} Alphanumeric + additional characters REQUIRED

The unique identifier issued to you by your payment provider.


This identifier can be up to 12 characters in length.


Data may consist of the characters 0-9, a-z, A-Z, '-', '_'

Min length: 1 Max length: 40

Fields

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.

Data can consist of any characters

Min length: 1 Max length: 100
session.id ASCII Text OPTIONAL

Identifier of the payment session containing values for any of the request fields to be used in this operation.

Values provided in the request will override values contained in the session.

Data consists of ASCII characters

Min length: 31 Max length: 35
session.version ASCII Text OPTIONAL

Use this field to implement optimistic locking of the session content.

Do this if you make business decisions based on data from the session and wish to ensure that the same data is being used for the request operation.

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.

Data consists of ASCII characters

Min length: 10 Max length: 10
transaction.currency Upper case alphabetic text OPTIONAL

The currency which should be used for acquirer card verification.

Not required for basic verification.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
verificationStrategy Enumeration OPTIONAL

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 or ACQUIRER you must also provide the card expiry date in the sourceOfFunds.provided.card.expiry parameter group.

Used to nominate which type of Verification to use when payment instrument details are stored in the token repository. This setting overrides the default settings in Merchant Manager.

Value must be a member of the following list. The values are case sensitive.

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.

Response

Fields

repositoryId ASCII Text CONDITIONAL

Unique identifier of the token repository.

Token repositories can be shared across merchants; however, a single merchant can be associated with only one token repository at a given time. Every token repository has a corresponding test token repository, which only the merchants with the corresponding test profiles can access. For example, if the repository ID is ABC, the test repository ID will be TestABC. Hence, the system displays an error if you specify a repository ID that starts with 'Test'

Data consists of ASCII characters

Min length: 1 Max length: 16
response.gatewayCode Enumeration CONDITIONAL

Summary of the success or otherwise of the Save operation.

Value must be a member of the following list. The values are case sensitive.

BASIC_VERIFICATION_SUCCESSFUL

The card number format was successfully verified and the card exists in a known range.

EXTERNAL_VERIFICATION_BLOCKED

The external verification was blocked due to risk rules.

EXTERNAL_VERIFICATION_DECLINED

The card details were sent for verification, but were was declined.

EXTERNAL_VERIFICATION_DECLINED_AUTHENTICATION_REQUIRED

The card details were sent for verification, but were declined as authentication required.

EXTERNAL_VERIFICATION_DECLINED_EXPIRED_CARD

The card details were sent for verification, but were declined as the card has expired.

EXTERNAL_VERIFICATION_DECLINED_INVALID_CSC

The card details were sent for verification, but were declined as the Card Security Code (CSC) was invalid.

EXTERNAL_VERIFICATION_PROCESSING_ERROR

There was an error processing the verification.

EXTERNAL_VERIFICATION_SUCCESSFUL

The card details were successfully verified.

NO_VERIFICATION_PERFORMED

The card details were not verified.

result Enumeration ALWAYS PROVIDED

A system-generated high level overall result of the Save operation.

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

A token is marked as invalid, if an Account Updater response indicates, that the card details stored against the token are invalid.

Transaction requests using an invalid token are rejected by the gateway.

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).

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.

usage CONDITIONAL

Information about the token.

usage.lastUpdated DateTime CONDITIONAL

The timestamp indicating the time the token was last updated.

An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"

usage.lastUpdatedBy Alphanumeric + additional characters CONDITIONAL

The identifier of the merchant who last updated the token.

Data may consist of the characters 0-9, a-z, A-Z, '-', '_'

Min length: 1 Max length: 40
usage.lastUsed DateTime CONDITIONAL

The timestamp indicating the time the token was last used or saved.

An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"

verificationStrategy Enumeration CONDITIONAL

The strategy used to verify the card details before they are stored.

If not provided, the verification strategy set on your merchant profile by your payment provider will be used.

Value must be a member of the following list. The values are case sensitive.

ACQUIRER

The gateway verifies the card details by performing an authorization for a nominal amount (for example, $1.00). The card details are sent to the acquirer for verification. This method requires your merchant profile to be configured with ""Auth Then Capture"" transaction mode.

BASIC

The gateway validates the card number format and checks if the card number falls within a valid BIN range.

NONE

The gateway does not perform card verification.

Errors

error

Information on possible error conditions that may occur while processing an operation using the API.

error.cause Enumeration

Broadly categorizes the cause of the error.

For example, errors may occur due to invalid requests or internal system failures.

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

Textual description of the error based on the cause.

This field is returned only if the cause is INVALID_REQUEST or SERVER_BUSY.

Data can consist of any characters

Min length: 1 Max length: 1000
error.field String

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.

Data can consist of any characters

Min length: 1 Max length: 100
error.supportCode String

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.

Data can consist of any characters

Min length: 1 Max length: 100
error.validationType Enumeration

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.

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

A system-generated high level overall result of the operation.

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.