Generate Payment Data

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

POST https://test-bankalfalah.gateway.mastercard.com/api/rest/version/100 / merchant / {merchantId} / token / {tokenid} / paymentData

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
{tokenid} Alphanumeric REQUIRED

Uniquely identifies a card and associated details.


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

Min length: 1 Max length: 40

Fields

To view the optional fields, please toggle on the "Show optional fields" setting.

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
responseControls OPTIONAL

Container for fields that control the response returned for the request.

responseControls.sensitiveData String OPTIONAL

Indicates how sensitive data is returned in the response.

Data can consist of any characters

Min length: 1 Max length: 50
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
correlationId Alphanumeric 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.

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

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

Data can consist of any characters

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

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.

schemeToken.provider Enumeration CONDITIONAL

The token service provider that generated a scheme token for the card details that are stored against the gateway token.

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

schemeToken.status Enumeration CONDITIONAL

The status of the scheme token stored against the gateway token.

ACTIVE A scheme token exists and can be used for transactions.
PROVISIONING The scheme token is being requested by the gateway.
SUSPENDED The scheme token has been blocked by the token service provider or issuer.
DEACTIVATED The scheme token has been permanently deleted by the token service provider or issuer.
INELIGIBLE The FPAN tokenization was declined by the token service provider or issuer.
TOKENIZATION_UNAVAILABLE The scheme token was not requested by the gateway as the pre-requisites are not met.

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

ACTIVE

A scheme token exists and can be used for transactions.

DEACTIVATED

The scheme token has been permanently deleted by the token service provider or issuer.

INELIGIBLE

The FPAN tokenization was declined by the token service provider or issuer.

PROVISIONING

The scheme token is being requested by the gateway.

SUSPENDED

The scheme token has been blocked by the token service provider or issuer.

TOKENIZATION_UNAVAILABLE

The scheme token was not requested by the gateway as the pre-requisites for scheme tokenization are not met.

schemeToken.statusTime DateTime CONDITIONAL

The timestamp indicating the date and time when the status of the scheme token was last updated.

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

sourceOfFunds ALWAYS PROVIDED

Details about the source of the funds for this payment.

sourceOfFunds.provided ALWAYS PROVIDED

The details of the source of funds when they are directly provided as opposed to via a token or session.

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

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.

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.devicePayment CONDITIONAL

Details about the card that you have sourced using digital payment methods.

sourceOfFunds.provided.card.devicePayment.eciIndicator Digits CONDITIONAL

The Electronic Commerce Indicator generated for payments made using a device payment method or a card scheme token.

Data is a string that consists of the characters 0-9.

Min length: 1 Max length: 2
sourceOfFunds.provided.card.devicePayment.onlinePaymentCryptogram Base64 CONDITIONAL

A cryptogram used to authenticate the transaction.

Data is Base64 encoded

Min length: 1 Max length: 128
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:

  • • Card scheme tokens: the expiry date for the Token PAN.

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.

Data is a number between 1 and 12 represented as a 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.

Data is a string that consists of the characters 0-9.

Min length: 2 Max length: 2
sourceOfFunds.provided.card.deviceSpecificNumber Masked digits CONDITIONAL

The payer's account number associated with a digital payment method.

Use this field for:

  • • Card Scheme Tokens: the token generated by a card scheme tokenization service. The token is used as an identifier of the payer's Primary Account Number (PAN) securely stored by the service.

Data is a string that consists of the characters 0-9, plus 'x' for masking

Min length: 9 Max length: 19
sourceOfFunds.provided.card.expiry CONDITIONAL

Expiry date, as shown on the card.

sourceOfFunds.provided.card.expiry.month Digits ALWAYS PROVIDED

Month, as shown on the card.

Months are numbered January=1, through to December=12.

Data is a number between 1 and 12 represented as a string.

sourceOfFunds.provided.card.expiry.year Digits ALWAYS PROVIDED

Year, as shown on the card.

The Common Era year is 2000 plus this value.

Data is a string that consists of the characters 0-9.

Min length: 2 Max length: 2
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.

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.

Data can consist of any characters

Min length: 0 Max 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.

Data can consist of any characters

Min length: 3 Max length: 50
sourceOfFunds.provided.card.nameOnCard String CONDITIONAL

The cardholder's name as printed on the card.

Data can consist of any characters

Min length: 1 Max length: 256
sourceOfFunds.provided.card.number Masked digits CONDITIONAL

The account number embossed onto the card.

Data is a string that consists of the characters 0-9, plus 'x' for masking

Min length: 9 Max length: 19
sourceOfFunds.provided.card.scheme Enumeration ALWAYS PROVIDED

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.

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.card.securityCode Digits CONDITIONAL

Card verification code, as printed on the back or front of the card or as provided for a card scheme token.

Card scheme tokens: VTS refers to this as a Dynamic Token Verification Value (DTVV). AETS calls it Dynamic Card Security Code (DCSC).

Data is a string that consists of the characters 0-9.

Min length: 3 Max length: 4
sourceOfFunds.type Enumeration ALWAYS PROVIDED

The payment method your payer has chosen for this payment.

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.

SCHEME_TOKEN

Use this value for payments using scheme tokens provided by Mastercard Digital Enablement Service (MDES), or Visa Token Service (VTS), or American Express Token Service (AETS).

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.

token Alphanumeric ALWAYS PROVIDED

A gateway token that contains account identifier details.

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

Min length: 1 Max length: 40
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.