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.

PUT https://test-gateway.mastercard.com/api/rest/version/35 / merchant / {merchantId} / token / {tokenid}

Authentication Copied to clipboard

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 Copied to clipboard

URL Parameters Copied to clipboard

{merchantId} Copied to clipboard 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} Copied to clipboard 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 Copied to clipboard

correlationId Copied to clipboard 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 Copied to clipboard OPTIONAL

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

responseControls.sensitiveData Copied to clipboard String OPTIONAL

Indicates how sensitive data is returned in the response.

Data can consist of any characters

Min length: 1 Max length: 50
session.id Copied to clipboard 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 Copied to clipboard 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
sourceOfFunds Copied to clipboard REQUIRED

Information about the payment type selected by the payer for this payment and the source of the funds.

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.

sourceOfFunds.provided Copied to clipboard OPTIONAL

Information about the source of funds when it is directly provided (as opposed to via a token or session).

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.

sourceOfFunds.provided.ach Copied to clipboard OPTIONAL

For ACH payments (sourceOfFunds.type=ACH) you must provide values for all fields within this parameter group, including details about the payers bank account as well as the type of ACH payment.

It is your responsibility to authenticate the payer and obtain authorization from the payer in accordance with the NACHA Operating Rules and Guidelines for the Standard Entry Class (SEC) associated with this payment. For details please refer to https://www.nacha.org/.

sourceOfFunds.provided.ach.accountType Copied to clipboard Enumeration OPTIONAL

An indicator identifying the type of bank account.

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

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

CONSUMER_CHECKING

Consumer Checking Account

CONSUMER_SAVINGS

Consumer Savings Account

CORPORATE_CHECKING

Business Checking Account

sourceOfFunds.provided.ach.bankAccountHolder Copied to clipboard String OPTIONAL

The name of the bank account holder, as it appears on the account at the receiving financial institution.

Retrieve this information from the payer.

Data can consist of any characters

Min length: 1 Max length: 28
sourceOfFunds.provided.ach.bankAccountNumber Copied to clipboard Alphanumeric + additional characters OPTIONAL

The identifier of the bank account at the receiving financial institution.

Retrieve this information from the payer.

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

Min length: 1 Max length: 17
sourceOfFunds.provided.ach.routingNumber Copied to clipboard Digits OPTIONAL

The identifier of the receiving financial institution.

Also known as:

  • Routing number,
  • Transit number, or
  • ABA number

Retrieve this information from the payer.

See also http://en.wikipedia.org/wiki/Routing_transit_number.

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

Min length: 9 Max length: 9
sourceOfFunds.provided.ach.secCode Copied to clipboard Enumeration OPTIONAL

Identifies the Standard Entry Class (SEC) code to be sent to the issuer.

The SEC is defined by NACHA and describes the origin and intent of the payment. For details please refer to https://www.nacha.org/.

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

PPD

An ACH debit or credit payment (B2C) that has been authorized by an authenticated customer in written form (signed or similarly authenticated). PPD is used for pre-arranged payments (e.g. employee payroll, mortgage payments, expense reimbursement).

TEL

An ACH debit payment (B2C) that has been authorized by an authenticated customer via phone. TEL may only be used if a relationship already exists between you and the consumer, or, the consumer initiates the contact with you.

WEB

An ACH debit payment (B2C) that has been authorized by an authenticated customer via the internet or a wireless network.

sourceOfFunds.provided.giftCard Copied to clipboard 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.

sourceOfFunds.provided.giftCard.expectedLocalBrand Copied to clipboard String OPTIONAL

Do not provide this field in your request unless instructed to do so by your payment service provider.

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.

Data can consist of any characters

Min length: 4 Max length: 50
sourceOfFunds.provided.giftCard.number Copied to clipboard Digits OPTIONAL

Card number as printed or embossed on the gift card.

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

Min length: 9 Max length: 19
sourceOfFunds.provided.giftCard.pin Copied to clipboard Digits OPTIONAL

PIN number for the gift card.

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

Min length: 4 Max length: 8
sourceOfFunds.token Copied to clipboard Alphanumeric OPTIONAL

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
sourceOfFunds.type Copied to clipboard Enumeration REQUIRED

The payment method your payer has chosen for this payment.

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

ACH

The payer chose to pay using an electronic fund transfer, to be processed via the Automated Clearing House (ACH) Network. You must provide the payer's bank account details and information about the type of ACH payment under the sourceOfFunds.provided.ach parameter group.

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 Copied to clipboard 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 Copied to clipboard 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 Copied to clipboard

Fields Copied to clipboard

correlationId Copied to clipboard 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 Copied to clipboard 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 Copied to clipboard 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 Copied to clipboard 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

sourceOfFunds Copied to clipboard CONDITIONAL

Details about the source of the funds for this payment.

sourceOfFunds.provided Copied to clipboard ALWAYS PROVIDED

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

sourceOfFunds.provided.ach Copied to clipboard CONDITIONAL

For ACH payments (sourceOfFunds.type=ACH) you must provide values for all fields within this parameter group, including details about the payers bank account as well as the type of ACH payment.

It is your responsibility to authenticate the payer and obtain authorization from the payer in accordance with the NACHA Operating Rules and Guidelines for the Standard Entry Class (SEC) associated with this payment. For details please refer to https://www.nacha.org/.

sourceOfFunds.provided.ach.accountIdentifier Copied to clipboard String CONDITIONAL

The unique identifier of the routing number and bank account at the receiving financial institution.

Retrieve this information from the payer.

Data can consist of any characters

Min length: 19 Max length: 27
sourceOfFunds.provided.ach.accountType Copied to clipboard Enumeration CONDITIONAL

An indicator identifying the type of bank account.

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

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

CONSUMER_CHECKING

Consumer Checking Account

CONSUMER_SAVINGS

Consumer Savings Account

CORPORATE_CHECKING

Business Checking Account

sourceOfFunds.provided.ach.bankAccountHolder Copied to clipboard String CONDITIONAL

The name of the bank account holder, as it appears on the account at the receiving financial institution.

Retrieve this information from the payer.

Data can consist of any characters

Min length: 1 Max length: 28
sourceOfFunds.provided.ach.bankAccountNumber Copied to clipboard Digits CONDITIONAL

The identifier of the bank account at the receiving financial institution.

Retrieve this information from the payer.

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

Min length: 9 Max length: 17
sourceOfFunds.provided.ach.routingNumber Copied to clipboard Digits CONDITIONAL

The identifier of the receiving financial institution.

Also known as:

  • Routing number,
  • Transit number, or
  • ABA number

Retrieve this information from the payer.

See also http://en.wikipedia.org/wiki/Routing_transit_number.

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

Min length: 9 Max length: 9
sourceOfFunds.provided.ach.secCode Copied to clipboard Enumeration CONDITIONAL

Identifies the Standard Entry Class (SEC) code to be sent to the issuer.

The SEC is defined by NACHA and describes the origin and intent of the payment. For details please refer to https://www.nacha.org/.

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

PPD

An ACH debit or credit payment (B2C) that has been authorized by an authenticated customer in written form (signed or similarly authenticated). PPD is used for pre-arranged payments (e.g. employee payroll, mortgage payments, expense reimbursement).

TEL

An ACH debit payment (B2C) that has been authorized by an authenticated customer via phone. TEL may only be used if a relationship already exists between you and the consumer, or, the consumer initiates the contact with you.

WEB

An ACH debit payment (B2C) that has been authorized by an authenticated customer via the internet or a wireless network.

sourceOfFunds.provided.card Copied to clipboard CONDITIONAL

Details as shown on the card.

sourceOfFunds.provided.card.brand Copied to clipboard 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.expiry Copied to clipboard Digits ALWAYS PROVIDED

Expiry date as shown on the card in the format MMYY where months are numbered, so that for January MM=01, through to December MM=12 and the Common Era year is 2000 plus the value YY

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

Min length: 4 Max length: 4
sourceOfFunds.provided.card.fundingMethod Copied to clipboard 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 Copied to clipboard 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 Copied to clipboard 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.number Copied to clipboard Masked digits CONDITIONAL

The account number embossed onto the card.

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.

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 Copied to clipboard Enumeration CONDITIONAL

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.giftCard Copied to clipboard CONDITIONAL

Details as shown on the Gift Card.

sourceOfFunds.provided.giftCard.brand Copied to clipboard 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.

LOCAL_BRAND_ONLY

The card does not have a global brand.

sourceOfFunds.provided.giftCard.localBrand Copied to clipboard 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: 1 Max length: 50
sourceOfFunds.provided.giftCard.number Copied to clipboard Masked digits CONDITIONAL

The account number embossed onto the card.

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.

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

Min length: 9 Max length: 19
sourceOfFunds.provided.giftCard.pin Copied to clipboard Masked digits CONDITIONAL

PIN number for the gift card.

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

Min length: 4 Max length: 8
sourceOfFunds.provided.giftCard.scheme Copied to clipboard Enumeration CONDITIONAL

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.

OTHER

The scheme of the card used in the transaction could not be identified.

sourceOfFunds.type Copied to clipboard Enumeration CONDITIONAL

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

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 Copied to clipboard 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.

token Copied to clipboard Alphanumeric CONDITIONAL

Uniquely identifies a card and associated details.

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

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

Min length: 1 Max length: 40
usage Copied to clipboard CONDITIONAL

Information about the token.

usage.lastUpdated Copied to clipboard 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 Copied to clipboard 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 Copied to clipboard 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 Copied to clipboard 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 Copied to clipboard

error Copied to clipboard

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

error.cause Copied to clipboard 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 Copied to clipboard 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 Copied to clipboard 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 Copied to clipboard 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 Copied to clipboard 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 Copied to clipboard 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.