Create or Update Token

Request for the gateway to store a payment instrument against a token, where you provide the token ID.

This may include:

  • credit or debit card details
  • device payment details
  • gift card details
  • ACH bank account details
  • Canadian Direct Debit bank account details
  • PayPal billing agreement details
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. Note that this rule is not enforced for PayPal Billing Agreement IDs.
  • The repository is configured for the Token Management Strategy Unique Account Identifier and 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 account identifier, breaking the uniqueness rule.

If the repository is configured for scheme tokenization, the gateway will attempt to generate a scheme token for the stored card details.

If you want to tokenize card details associated to a previously successful payment, you can provide the order identifier of that payment using the field referenceOrderId. The order identifier provided in referenceOrderId must have card as the payment method, which includes both FPAN and DPAN based transactions. If it is the latter, the gateway won't attempt scheme tokenization even if you are enabled for scheme tokenization.

The gateway does not currently have support to store PayPal payment details against a gateway token.

However, you can
  • use this operation to store existing PayPal billing agreement details against a gateway token, for example, when migrating to the gateway.
  • use the Create or Update Browser Payment Token operation to create or update a gateway token with PayPal billing agreement details.

If you provide a shipping address or shipping contact details, these will be ignored unless the token contains PayPal billing agreement details.

Note that the name on the card, billing address details, and customer details are only used by the gateway when submitting the tokenization request to the token service provider. These details are not stored against the gateway token.

If you tokenize card details provided by a payer via their issuer (i.e. push provisioning of scheme tokens), use this operation to supply the reference provided by the issuer for provisioning the scheme token. This reference will be used by the gateway to retrieve the scheme token and card details from the token service provider e.g. MDES.

PUT https://api/rest/version/100 / 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

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

billing Copied to clipboard OPTIONAL

Details of the payer's billing address.

billing.address Copied to clipboard OPTIONAL

The payer's billing address.

This data may be used to qualify for better interchange rates on corporate purchase card transactions.

billing.address.city Copied to clipboard String OPTIONAL

The city portion of the address.

Data can consist of any characters

Min length: 1 Max length: 100
billing.address.company Copied to clipboard String OPTIONAL

The name of the company associated with this address.

Data can consist of any characters

Min length: 1 Max length: 100
billing.address.country Copied to clipboard Upper case alphabetic text OPTIONAL

The 3 letter ISO standard alpha country code of the address.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
billing.address.postcodeZip Copied to clipboard Alphanumeric + additional characters OPTIONAL

The post code or zip code of the address.

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

Min length: 1 Max length: 10
billing.address.stateProvince Copied to clipboard String OPTIONAL

The state or province of the address.

Data can consist of any characters

Min length: 1 Max length: 20
billing.address.stateProvinceCode Copied to clipboard String OPTIONAL

The three character ISO 3166-2 country subdivision code for the state or province of the address.

Providing this field might improve your payer experience for 3-D Secure payer authentication.

Data can consist of any characters

Min length: 1 Max length: 3
billing.address.street Copied to clipboard String OPTIONAL

The first line of the address.

For example, this may be the street name and number, or the Post Office Box details.

Data can consist of any characters

Min length: 1 Max length: 100
billing.address.street2 Copied to clipboard String OPTIONAL

The second line of the address (if provided).

Data can consist of any characters

Min length: 1 Max length: 100
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
customer Copied to clipboard OPTIONAL

Information about the customer, including their contact details.

customer.email Copied to clipboard Email OPTIONAL

The email address of the customer.

The field format restriction ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses.

Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses

customer.firstName Copied to clipboard String OPTIONAL

The customer's first name.

Data can consist of any characters

Min length: 1 Max length: 50
customer.lastName Copied to clipboard String OPTIONAL

The customer's last or surname.

Data can consist of any characters

Min length: 1 Max length: 50
customer.mobilePhone Copied to clipboard Telephone Number OPTIONAL

The customer's mobile phone or cell phone number in ITU-T E123 format, for example +1 607 1234 5678

The number consists of:

  • '+'
  • country code (1, 2 or 3 digits)
  • 'space'
  • national number ( which may embed single spaces characters for readability).

Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)

Mandatory country code: true Max total digits: 15
customer.phone Copied to clipboard Telephone Number OPTIONAL

The customer's phone number in ITU-T E123 format, for example +1 607 1234 456

The number consists of:

  • '+'
  • country code (1, 2 or 3 digits)
  • 'space'
  • national number ( which may embed single spaces characters for readability).

Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)

Mandatory country code: true Max total digits: 15
customer.taxRegistrationId Copied to clipboard String OPTIONAL

The tax registration identifier of the customer.

Data can consist of any characters

Min length: 1 Max length: 30
device Copied to clipboard OPTIONAL

Information about the device used by the payer for this transaction.

device.ipAddress Copied to clipboard String OPTIONAL

The IP address of the device used by the payer, in IPv4 nnn.nnn.nnn.nnn format.

You can provide the IP address in IPv6 format as defined in RFC4291.
IPv6 address will only be used in EMV 3DS authentication. Supplied IPv6 address will not be used for any other purposes.

Data can consist of any characters

Min length: 7 Max length: 45
referenceOrderId Copied to clipboard String OPTIONAL

This is the reference to an order previously submitted by you to the gateway.

It is applicable to the following scenarios.

Tokenization requests:
Identifier for the order which will be used to generate a gateway token. The gateway will attempt tokenization of payment credentials linked to the order ID.
The order identifier provided in this field must be linked to a successfully processed order which has card (FPAN / DPAN) as the payment method.
When providing this field, you must not provide card details in the sourceOfFunds.provided.card parameter group.

Payment transactions:
When submitting:

  • an industry practice payment, this is the reference to the initial cardholder-initiated transaction.
  • a resubmission transaction, this is the reference to the order which is being resubmitted.

Data can consist of any characters

Min length: 1 Max length: 40
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
shipping Copied to clipboard OPTIONAL

Information on the shipping address including the contact details of the addressee.

These details will only be stored against the token if the request is for storing PayPal billing agreement details.

shipping.address Copied to clipboard OPTIONAL

The address to which this order will be shipped.

shipping.address.city Copied to clipboard String OPTIONAL

The city portion of the address.

Data can consist of any characters

Min length: 1 Max length: 100
shipping.address.country Copied to clipboard Upper case alphabetic text OPTIONAL

The 3 letter ISO standard alpha country code of the address.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
shipping.address.postcodeZip Copied to clipboard Alphanumeric + additional characters OPTIONAL

The post code or zip code of the address.

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

Min length: 1 Max length: 10
shipping.address.stateProvince Copied to clipboard String OPTIONAL

The state or province of the address.

Data can consist of any characters

Min length: 1 Max length: 20
shipping.address.street Copied to clipboard String OPTIONAL

The first line of the address.

For example, this may be the street name and number, or the Post Office Box details.

Data can consist of any characters

Min length: 1 Max length: 100
shipping.address.street2 Copied to clipboard String OPTIONAL

The second line of the address (if provided).

Data can consist of any characters

Min length: 1 Max length: 100
shipping.contact Copied to clipboard OPTIONAL

Details of the contact person at the address the goods will be shipped to.

shipping.contact.firstName Copied to clipboard String OPTIONAL

The first name of the person to whom the order is being shipped.

Data can consist of any characters

Min length: 1 Max length: 50
shipping.contact.lastName Copied to clipboard String OPTIONAL

The last name or surname of the person to whom the order is being shipped.

Data can consist of any characters

Min length: 1 Max length: 50
shipping.origin.postcodeZip Copied to clipboard Alphanumeric + additional characters OPTIONAL

The post code or zip code of the address the order is shipped from.

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

Min length: 1 Max length: 10
subMerchant Copied to clipboard OPTIONAL

Provide these parameters if you are a payment aggregator or facilitator and process payments on behalf of other merchants.

These merchants are referred to as your sub merchants. The sub merchant's details you provide may be displayed on the payer's cardholder statement. The gateway will use separate token repositories for each of your sub merchants

subMerchant.identifier Copied to clipboard Alphanumeric + additional characters REQUIRED

Your identifier for the sub-merchant.

Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '.'

Min length: 1 Max length: 100
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 you must also provide the card expiry date in the sourceOfFunds.provided.card.expiry parameter group.
  • ACQUIRER you must also provide the card expiry date in the sourceOfFunds.provided.card.expiry parameter group and the currency in the transaction.currency field.
  • ACCOUNT_UPDATER you must also provide a currency in the transaction.currency field and the sourceOfFunds parameter group is optional.
To use this operation to request an account update
  • you need to be enabled for Account Updater by your payment service provider.
  • you can subsequently inquire about any updates the gateway has made to the token based on the Account Updater response using the RETRIEVE_TOKEN or SEARCH_TOKENS operations.
As a result of an account update the payment details stored against the token may be updated or the token may be marked as invalid. Any updates made to the payment details respect the token management strategy configured for your token repository. For example, if the token repository is configured with a token generation strategy of Preserve 6.4 and an account update indicates that the card number has changed, the token is marked as invalid. You can no longer use an invalid token and must ask your payer for new payment details.

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

billing Copied to clipboard CONDITIONAL

Information on the billing address, including the contact details of the payer.

For card payments, this information may be used by the issuer to verify the payer, so must match the billing address details the payer registered with their issuer.

billing.address Copied to clipboard CONDITIONAL

The payer's billing address.

This data may be used to qualify for better interchange rates on corporate purchase card transactions.

billing.address.city Copied to clipboard String CONDITIONAL

The city portion of the address.

Data can consist of any characters

Min length: 1 Max length: 100
billing.address.company Copied to clipboard String CONDITIONAL

The name of the company associated with this address.

Data can consist of any characters

Min length: 1 Max length: 100
billing.address.country Copied to clipboard Upper case alphabetic text CONDITIONAL

The 3 letter ISO standard alpha country code of the address.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
billing.address.postcodeZip Copied to clipboard Alphanumeric + additional characters CONDITIONAL

The post code or zip code of the address.

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

Min length: 1 Max length: 10
billing.address.stateProvince Copied to clipboard String CONDITIONAL

The state or province of the address.

Data can consist of any characters

Min length: 1 Max length: 20
billing.address.stateProvinceCode Copied to clipboard String CONDITIONAL

The three character ISO 3166-2 country subdivision code for the state or province of the address.

Providing this field might improve your payer experience for 3-D Secure payer authentication.

Data can consist of any characters

Min length: 1 Max length: 3
billing.address.street Copied to clipboard String CONDITIONAL

The first line of the address.

For example, this may be the street name and number, or the Post Office Box details.

Data can consist of any characters

Min length: 1 Max length: 100
billing.address.street2 Copied to clipboard String CONDITIONAL

The second line of the address (if provided).

Data can consist of any characters

Min length: 1 Max length: 100
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
customer Copied to clipboard CONDITIONAL

Information about the customer, including their contact details.

customer.email Copied to clipboard Email CONDITIONAL

The email address of the customer.

The field format restriction ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses.

Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses

customer.firstName Copied to clipboard String CONDITIONAL

The customer's first name.

Data can consist of any characters

Min length: 1 Max length: 50
customer.lastName Copied to clipboard String CONDITIONAL

The customer's last or surname.

Data can consist of any characters

Min length: 1 Max length: 50
customer.mobilePhone Copied to clipboard String CONDITIONAL

The customer's mobile phone or cell phone number in ITU-T E123 format, for example +1 607 1234 5678

The number consists of:

  • '+'
  • country code (1, 2 or 3 digits)
  • 'space'
  • national number ( which may embed single spaces characters for readability).

Data can consist of any characters

Min length: 1 Max length: 20
customer.phone Copied to clipboard String CONDITIONAL

The customer's phone number in ITU-T E123 format, for example +1 607 1234 456

The number consists of:

  • '+'
  • country code (1, 2 or 3 digits)
  • 'space'
  • national number ( which may embed single spaces characters for readability).

Data can consist of any characters

Min length: 1 Max length: 20
customer.taxRegistrationId Copied to clipboard String CONDITIONAL

The tax registration identifier of the customer.

Data can consist of any characters

Min length: 1 Max length: 30
device Copied to clipboard CONDITIONAL

The IP address of the device used by the payer, in IPv4 nnn.nnn.nnn.nnn format.

You can provide the IP address in IPv6 format as defined in RFC4291.
IPv6 address will only be used in EMV 3DS authentication. Supplied IPv6 address will not be used for any other purposes.

device.ipAddress Copied to clipboard String CONDITIONAL

The IP address of the device used by the payer, in IPv4 nnn.nnn.nnn.nnn format.

You can provide the IP address in IPv6 format as defined in RFC4291.
IPv6 address will only be used in EMV 3DS authentication. Supplied IPv6 address will not be used for any other purposes.

Data can consist of any characters

Min length: 7 Max length: 45
referenceOrderId Copied to clipboard String CONDITIONAL

This is the reference to an order previously submitted by you to the gateway.

It is applicable to the following scenarios.

Tokenization requests:
Identifier for the order which will be used to generate a gateway token. The gateway will attempt tokenization of payment credentials linked to the order ID.
The order identifier provided in this field must be linked to a successfully processed order which has card (FPAN / DPAN) as the payment method.
When providing this field, you must not provide card details in the sourceOfFunds.provided.card parameter group.

Payment transactions:
When submitting:

  • an industry practice payment, this is the reference to the initial cardholder-initiated transaction.
  • a resubmission transaction, this is the reference to the order which is being resubmitted.

Data can consist of any characters

Min length: 1 Max length: 40
replacementToken Copied to clipboard Alphanumeric CONDITIONAL

If a replacement token for this token is provided, you must

  • start using the replacement token instead of this token and
  • delete this token

If a replacement token is provided, this token is not marked as invalid (status=INVALID) and has been updated to allow you to keep using it until you have started using the replacement token.

However, you will no longer be able to update this token. For more details see Gateway Tokenization

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

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

SCHEME_TOKENIZATION_DECLINED

The card details that your payer has made available to you via their card issuer (for push provisioning) could not be tokenized. The request was declined by the token service provider or issuer.

SCHEME_TOKENIZATION_ERROR

The card details that your payer has made available to you via their card issuer (for push provisioning) could not be tokenized. The token service provider returned an error response.

SCHEME_TOKENIZATION_SUCCESSFUL

The card details your payer has made available to you via their card issuer (for push provisioning) were successfully tokenized by the token service provider.

SCHEME_TOKENIZATION_SUCCESSFUL_ADDITIONAL_AUTHENTICATION_REQUIRED

The card details your payer has made available to you via their card issuer (for push provisioning) were successfully tokenized by the token service provider, but the issuer needs to perform additional authentication of the cardholder.

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

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

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

This field is returned once the token service provider can be identified. Note that it does not imply that a scheme token is available for use.

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 Copied to clipboard 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 for scheme tokenization 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 Copied to clipboard 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"

schemeToken.tokenIdentifier Copied to clipboard String CONDITIONAL

The unique identifier for the scheme token as assigned by the token service provider.

The Mastercard Digital Enablement Service (MDES) calls this 'Token Unique Reference' (TUR).

Data can consist of any characters

Min length: 1 Max length: 64
schemeTokenProvisioningMode Copied to clipboard Enumeration CONDITIONAL

The mode used to create a gateway token and obtain a scheme token from the token service provider.

You only need to specify the scheme token provisioning mode if you want to override the default value configured for your token repository.

You can refer to the schemeToken.status field in the response for the status of the scheme token stored against the gateway token.

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

ASYNCHRONOUS

The gateway token is generated and immediately returned to you in the response. The network token will then be requested and, if successful, linked to the gateway token.

ATTEMPT_SYNCHRONOUS

The gateway token is generated and the network token is immediately requested. If successful, it is linked to the gateway token, and you receive the response. If unsuccessful, the gateway token is still returned, with the network token generation re-tried again later.

SYNCHRONOUS

The network token is requested immediately. If successful, the gateway token is returned in the response. Otherwise, an error response is returned and the gateway token is not created.

shipping Copied to clipboard CONDITIONAL

Information on the shipping address including the contact details of the addressee.

These details will only be stored against the token if the request is for storing PayPal billing agreement details.

shipping.address Copied to clipboard CONDITIONAL

The address to which this order will be shipped.

shipping.address.city Copied to clipboard String CONDITIONAL

The city portion of the address.

Data can consist of any characters

Min length: 1 Max length: 100
shipping.address.country Copied to clipboard Upper case alphabetic text CONDITIONAL

The 3 letter ISO standard alpha country code of the address.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
shipping.address.postcodeZip Copied to clipboard Alphanumeric + additional characters CONDITIONAL

The post code or zip code of the address.

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

Min length: 1 Max length: 10
shipping.address.stateProvince Copied to clipboard String CONDITIONAL

The state or province of the address.

Data can consist of any characters

Min length: 1 Max length: 20
shipping.address.street Copied to clipboard String CONDITIONAL

The first line of the address.

For example, this may be the street name and number, or the Post Office Box details.

Data can consist of any characters

Min length: 1 Max length: 100
shipping.address.street2 Copied to clipboard String CONDITIONAL

The second line of the address (if provided).

Data can consist of any characters

Min length: 1 Max length: 100
shipping.contact Copied to clipboard CONDITIONAL

Details of the contact person at the address the goods will be shipped to.

shipping.contact.firstName Copied to clipboard String CONDITIONAL

The first name of the person to whom the order is being shipped.

Data can consist of any characters

Min length: 1 Max length: 50
shipping.contact.lastName Copied to clipboard String CONDITIONAL

The last name or surname of the person to whom the order is being shipped.

Data can consist of any characters

Min length: 1 Max length: 50
shipping.origin.postcodeZip Copied to clipboard Alphanumeric + additional characters CONDITIONAL

The post code or zip code of the address the order is shipped from.

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

Min length: 1 Max length: 10
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.card Copied to clipboard 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.
Device payment methods such as Apple Pay, Android Pay, Samsung Pay or Google Pay.
Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout.
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 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.deviceSpecificExpiry Copied to clipboard 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:

  • • Device payments: the expiry date for the Device Primary Account Number (DPAN).
  • • Digital wallets: the expiry date for the Token PAN.

sourceOfFunds.provided.card.deviceSpecificExpiry.month Copied to clipboard 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 Copied to clipboard 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 Copied to clipboard Masked digits CONDITIONAL

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

Use this field for:

  • • Device payments: the payer's account number associated with the mobile device used for the payment. This is also known as the Device Primary Account Number (DPAN).
  • • Digital wallets: the Token PAN returned by a digital wallet. The gateway only returns this value for Amex Express Checkout.

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

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

sourceOfFunds.provided.directDebitCanada.accountType Copied to clipboard Enumeration CONDITIONAL

An indicator identifying the type of bank account.

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

CONSUMER_CHECKING

Consumer Checking Account

CONSUMER_SAVINGS

Consumer Savings Account

sourceOfFunds.provided.directDebitCanada.bankAccountHolder Copied to clipboard String ALWAYS PROVIDED

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.directDebitCanada.bankAccountNumber Copied to clipboard Alphanumeric + additional characters ALWAYS PROVIDED

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: 7 Max length: 12
sourceOfFunds.provided.directDebitCanada.financialInstitutionNumber Copied to clipboard Digits ALWAYS PROVIDED

The identifier of the receiving financial institution.

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

Min length: 3 Max length: 3
sourceOfFunds.provided.directDebitCanada.transitNumber Copied to clipboard Digits ALWAYS PROVIDED

The transit number identifying the branch of the receiving financial institution where the bank account is held.

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

Min length: 5 Max length: 5
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.schemeTokenProvisioningIdentifier Copied to clipboard ASCII Text CONDITIONAL

You only must provide this field if you want the gateway to retrieve a scheme token for card details that your payer has made available to you via their card issuer (i.e. push provisioning of scheme tokens).

Using the identifier provided by the issuer, the gateway will retrieve the scheme token details from the token service provider and store them against the gateway token.

When providing this field, you must not provide card details in the sourceOfFunds.provided.card parameter group, and you must set the sourceOfFunds.type field to CARD.

Data consists of ASCII characters

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

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.

DIRECT_DEBIT_CANADA

The payer chose to pay using Direct Debit in Canada, also known as pre-authorized bank debits (PADs). You must provide the payer's bank account details in the sourceOfFunds.provided.directDebitCanada parameter group.

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

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.

subMerchant Copied to clipboard CONDITIONAL

Provide these parameters if you are a payment aggregator or facilitator and process payments on behalf of other merchants.

These merchants are referred to as your sub merchants. The sub merchant's details you provide may be displayed on the payer's cardholder statement. The gateway will use separate token repositories for each of your sub merchants

subMerchant.identifier Copied to clipboard Alphanumeric + additional characters ALWAYS PROVIDED

Your identifier for the sub-merchant.

Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '.'

Min length: 1 Max length: 100
token Copied to clipboard Alphanumeric CONDITIONAL

On request, supply the token you wish to create or update.

You can only supply this value when creating a token if your token repository is configured to support merchant-supplied tokens.

On response, the format of the token depends on the token generation strategy configured for your repository. See Tokenization for more details.

You will receive a new token in field replacementToken when:

  • Your token repository is configured to use a 6.4 Token Generation Strategy, and
  • You set request.verificationStrategy = ACCOUNT_UPDATER or you are configured for the Token Maintenance Service functionality, and
  • The Account Updater service provided a new account identifier (with a different 6.4 mask).


You should use the new token in future operation requests and delete the old token.

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 usage of the token.

usage.lastUpdated.merchantId Copied to clipboard Alphanumeric + additional characters CONDITIONAL

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

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

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"

verificationStrategy Copied to clipboard Enumeration CONDITIONAL

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 you must also provide the card expiry date in the sourceOfFunds.provided.card.expiry parameter group.
  • ACQUIRER you must also provide the card expiry date in the sourceOfFunds.provided.card.expiry parameter group and the currency in the transaction.currency field.
  • ACCOUNT_UPDATER you must also provide a currency in the transaction.currency field and the sourceOfFunds parameter group is optional.
To use this operation to request an account update
  • you need to be enabled for Account Updater by your payment service provider.
  • you can subsequently inquire about any updates the gateway has made to the token based on the Account Updater response using the RETRIEVE_TOKEN or SEARCH_TOKENS operations.
As a result of an account update the payment details stored against the token may be updated or the token may be marked as invalid. Any updates made to the payment details respect the token management strategy configured for your token repository. For example, if the token repository is configured with a token generation strategy of Preserve 6.4 and an account update indicates that the card number has changed, the token is marked as invalid. You can no longer use an invalid token and must ask your payer for new payment details.

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.

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.