Save card (with system-generated token)

Request for the gateway to store card information 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 will be configured by your gateway provider for you.

If you are configured to use a Random or Preserve 6.4 token generation strategy, use this call to create the token. If you use a Merchant-Supplied generation strategy, do not use this call.

Typically, this call will return a new token. However, if you are configured to use a Unique Card Number repository and the supplied card number has been previously stored against an existing token, we will return that token.

URL https://ap-gateway.mastercard.com/api/rest/version/28/merchant/{merchantId}/token
HTTP Method POST
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 Parameters

sourceOfFunds   = COMPULSORY

Depending on the payment type the source of the funds can be a debit or credit card, bank account, or account with a browser payment provider (such as PayPal).

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

sourceOfFunds.type  Enumeration = COMPULSORY

Existence
COMPULSORY
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
CARD
The payer selected to pay using a credit or debit card. The payer's card details must be provided.
GIFT_CARD
The payer chose to pay using gift card. The payer's gift card details must be provided under the sourceOfFunds.provided.giftCard parameter group.

cardVerificationStrategy  Enumeration = OPTIONAL

If not provided the verification strategy on the merchant profile will be used to verify the card details on the request.
Existence
OPTIONAL
Fixed value
Validation Rules
Used to nominate which type of Card Verification to use when card details are stored in the token repository. This setting overrides the default settings in Merchant Manager.
JSON type
String
Value must be a member of the following list. The values are case sensitive.
ACQUIRER
Verifies that the card is valid by performing an Authorize transaction for an nominal amount (e.g.$1.00)
BASIC
Verifies the card number is valid and that the card number falls within a valid BIN range
NONE
No verification of the card details are performed

correlationId  String = OPTIONAL

The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

responseControls   = OPTIONAL

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

responseControls.sensitiveData  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

session.id  ASCII Text = OPTIONAL

Values provided in the request will override values contained in the session.
Existence
OPTIONAL
Fixed value
Validation Rules
Data consists of ASCII characters
JSON type
String
minimum length
31
maximum length
35

session.version  ASCII Text = OPTIONAL

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.
Existence
OPTIONAL
Fixed value
Validation Rules
Data consists of ASCII characters
JSON type
String
minimum length
10
maximum length
10

sourceOfFunds   = COMPULSORY

Depending on the payment type the source of the funds can be a debit or credit card, bank account, or account with a browser payment provider (such as PayPal).

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

sourceOfFunds.provided   = OPTIONAL

For browser payments, the source of funds details are usually collected from the payer on the payment provider's website and provided to you when you retrieve the transaction details (for a successful transaction). However, for some payment types (such as giropay), you must collect the information from the payer and supply it here.
Fixed value

sourceOfFunds.provided.giftCard   = OPTIONAL

If the payer chose to pay using a gift card, you must submit sourceOfFunds.type=GIFT_CARD and provide the payer's gift card details in this parameter group.
Fixed value

sourceOfFunds.provided.giftCard.expectedLocalBrand  String = OPTIONAL

The field is required, if your gift card numbers do not use ISO BIN rules and therefore not allowing the gateway to identify the local brand.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
4
maximum length
50

sourceOfFunds.provided.giftCard.number  Digits = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
JSON type
String
minimum length
9
maximum length
19

sourceOfFunds.provided.giftCard.pin  Digits = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
JSON type
String
minimum length
4
maximum length
8

sourceOfFunds.token  Alphanumeric = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
JSON type
String
minimum length
1
maximum length
40

sourceOfFunds.type  Enumeration = COMPULSORY

Existence
COMPULSORY
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
CARD
The payer selected to pay using a credit or debit card. The payer's card details must be provided.
GIFT_CARD
The payer chose to pay using gift card. The payer's gift card details must be provided under the sourceOfFunds.provided.giftCard parameter group.

transaction.currency  Upper case alphabetic text = OPTIONAL

Not required for basic verification.
Existence
OPTIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
JSON type
String
minimum length
3
maximum length
3

{merchantId}  Alphanumeric + additional characters COMPULSORY

Existence
COMPULSORY
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_'
XSD type
string
minimum length
1
maximum length
40

Response Parameters

result  Enumeration = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
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

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).
Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
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.

correlationId  String = CONDITIONAL

The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

repositoryId  ASCII Text = CONDITIONAL

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'
Existence
CONDITIONAL
Fixed value
Validation Rules
Data consists of ASCII characters
JSON type
String
minimum length
1
maximum length
16

response.gatewayCode  Enumeration = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
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

Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
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

sourceOfFunds   = CONDITIONAL

Details about the source of the funds for this payment.
Fixed value

sourceOfFunds.provided   = Always Provided

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

sourceOfFunds.provided.card   = CONDITIONAL

Details as shown on the card.
Fixed value

sourceOfFunds.provided.card.brand  Enumeration = Always Provided

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.
Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
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.expiry  Digits = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
JSON type
String
minimum length
4
maximum length
4

sourceOfFunds.provided.card.fundingMethod  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.
Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
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.localBrand  Enumeration = CONDITIONAL

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.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
BANAMEX_COSTCO
Banamex Costco (Mexico)
BANKAXEPT
BankAxept (Norway)
BED_BATH_AND_BEYOND
Bed Bath & Beyond
CARNET
Carnet (Mexico)
CARTE_BANCAIRE
Carte Bancaire (France)
COSTCO_MEMBER_CREDIT
Costco Member Credit
EBT
Electronic Benefit Transfer (USA)
EFTPOS
Eftpos(Aus)
ELO
Elo (Brazil)
FARMERS
Farmers Card (New Zealand)
GIROCARD_JCB
Girocard (JCB)
GIROCARD_MAESTRO
Girocard (Maestro)
GIROCARD_VISA
Girocard (Visa)
LASER
Laser (Ireland)
OTHER
Other local card brand
PAGOBANCOMAT
PagoBANCOMAT (Italy)
Q_CARD
Q Card (New Zealand)
SORIANA
Soriana (Mexico)
TRUE_REWARDS
True Rewards (New Zealand)

sourceOfFunds.provided.card.number  Masked digits = CONDITIONAL

By default, the card number will be returned in 6.4 masking format, for example, 000000xxxxxx0000.If you wish to return unmasked card numbers, you must have the requisite permission, set responseControls.sensitiveData field to UNMASK, and authenticate your call to the API using certificate authentication.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9, plus 'x' for masking
JSON type
String
minimum length
9
maximum length
19

sourceOfFunds.provided.card.scheme  Enumeration = CONDITIONAL

The card scheme also controls authorization and settlement of card transactions among issuers and acquirers.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
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.giftCard   = CONDITIONAL

Details as shown on the Gift Card.
Fixed value

sourceOfFunds.provided.giftCard.brand  Enumeration = Always Provided

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.
Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
LOCAL_BRAND_ONLY
The card does not have a global brand.

sourceOfFunds.provided.giftCard.fundingMethod  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.
Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
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.giftCard.localBrand  String = CONDITIONAL

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.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

sourceOfFunds.provided.giftCard.number  Masked digits = CONDITIONAL

By default, the card number will be returned in 6.4 masking format, for example, 000000xxxxxx0000.If you wish to return unmasked card numbers, you must have the requisite permission, set responseControls.sensitiveData field to UNMASK, and authenticate your call to the API using certificate authentication.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9, plus 'x' for masking
JSON type
String
minimum length
9
maximum length
19

sourceOfFunds.provided.giftCard.pin  Masked digits = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9, plus 'x' for masking
JSON type
String
minimum length
4
maximum length
8

sourceOfFunds.provided.giftCard.scheme  Enumeration = CONDITIONAL

The card scheme also controls authorization and settlement of card transactions among issuers and acquirers.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
OTHER
The scheme of the card used in the transaction could not be identified.

sourceOfFunds.type  Enumeration = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
CARD
The payer selected to pay using a credit or debit card. The payer's card details must be provided.
GIFT_CARD
The payer chose to pay using gift card. The payer's gift card details must be provided under the sourceOfFunds.provided.giftCard parameter group.

status  Enumeration = Always Provided

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).
Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
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 = CONDITIONAL

The format of this token id depends on the Tokenization Strategy configured for the merchant:
  • 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
Existence
CONDITIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
JSON type
String
minimum length
1
maximum length
40

usage   = CONDITIONAL

Information about the token.
Fixed value

usage.lastUpdated  DateTime = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"
JSON type
String

usage.lastUpdatedBy  Alphanumeric + additional characters = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_'
JSON type
String
minimum length
1
maximum length
40

usage.lastUsed  DateTime = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"
JSON type
String

verificationStrategy  Enumeration = CONDITIONAL

If not provided, the verification strategy set on your merchant profile by your payment provider will be used.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
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.

error   = CONDITIONAL

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

error.cause  Enumeration = CONDITIONAL

For example, errors may occur due to invalid requests or internal system failures.
Fixed value
Validation Rules
JSON type
String
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 = CONDITIONAL

This field is returned only if the cause is INVALID_REQUEST or SERVER_BUSY.
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
1000

error.field  String = CONDITIONAL

This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

error.supportCode  String = CONDITIONAL

This field is returned only if the cause is SERVER_FAILED or REQUEST_REJECTED.
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

error.validationType  Enumeration = CONDITIONAL

This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.
Fixed value
Validation Rules
JSON type
String
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 = CONDITIONAL

Fixed value
Validation Rules
JSON type
String
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.

Copyright © 2023 MasterCard