Generate Payment Data

Request to obtain the payment details for the specified token that can be used for a payment authorization.

POST https://anzegate.gateway.mastercard.com/api/nvp/version/100

Authentication

This operation requires authentication via one of the following methods:


  • Certificate authentication.
  • To authenticate to the API two additional NVP parameters must be supplied in the request. Provide 'merchant.<your gateway merchant ID>' in the apiUsername field and your API password in the apiPassword field.

Request

Fields

apiOperation String = GENERATE_PAYMENT_DATA FIXED

Any sequence of zero or more unicode characters.

authentication OPTIONAL

Information about how the payer's identity is verified, if applicable.

For example, where a payer has a stored card associated with a scheme token that is verified using Mastercard's Token Authentication Framework (TAF).

authentication.orderId String REQUIRED

The orderId you used for the Initiate Authentication operation.

Data can consist of any characters

Min length: 1 Max length: 40
authentication.transactionId String REQUIRED

The transactionId you used for the Initiate Authentication operation.

Data can consist of any characters

Min length: 1 Max length: 40
correlationId Alphanumeric 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 may consist of the characters 0-9, a-z, A-Z

Min length: 1 Max length: 100
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
schemeToken OPTIONAL

Where a scheme token is stored against this gateway token, this group contains details about the scheme token, such as the token service provider.

schemeToken.preferredCryptogramType Enumeration OPTIONAL

The type of verification data you require for the scheme token:

  • CRYPTOGRAM - a full cryptogram,
  • VERIFICATION_CODE – an alternative to the full cryptogram. VTS refers to this as a Dynamic Token Verification Value (DTVV).

While the gateway will consider your preference, the cryptogram type returned in the response will also depend on the cryptogram type the token service provider supports.

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

CRYPTOGRAM

A full cryptogram

VERIFICATION_CODE

A scheme specific alternative to the full cryptogram.

Response

Fields

authentication CONDITIONAL

Information about how the payer's identity is verified, if applicable.

For example, where a payer has a stored card associated with a scheme token that is verified using Mastercard's Token Authentication Framework (TAF).

authentication.orderId String ALWAYS PROVIDED

The orderId you used for the Initiate Authentication operation.

Data can consist of any characters

Min length: 1 Max length: 40
authentication.transactionId String ALWAYS PROVIDED

The transactionId you used for the Initiate Authentication operation.

Data can consist of any characters

Min length: 1 Max length: 40
repositoryId ASCII Text ALWAYS PROVIDED

The unique identifier of the token repository associated with the merchant.

Data consists of ASCII characters

Min length: 1 Max length: 16
result Enumeration ALWAYS PROVIDED

A system-generated high level overall result of the 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, token service provider, 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:

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

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


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 ALWAYS PROVIDED

Information about the usage of the token.

usage.lastUpdated ALWAYS PROVIDED

Information about the most recent change made to the token.

usage.lastUpdated.merchantId Alphanumeric + additional characters ALWAYS PROVIDED

If the token was last updated by a merchant this field contains the merchant ID of the merchant that made the update.

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

Min length: 1 Max length: 40
usage.lastUpdated.source Enumeration ALWAYS PROVIDED

Indicates the source of the last update to the token.

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 ALWAYS PROVIDED

The timestamp indicating the date and time the token was last updated.

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

usage.lastUsedTime DateTime ALWAYS PROVIDED

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

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

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.