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
  • gift card details
  • ACH 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 you provide a shipping address or shipping contact details, these will be ignored.

URL https://egenius.unicredit.ro/api/nvp/version/64
HTTP Method POST
Authentication This operation requires authentication via one of the following methods:
  • Certificate authentication.
  • To authenticate to the API two additional NVP parameters must be supplied in the request. Provide 'merchant.<your gateway merchant ID>' in the apiUsername field and your API password in the apiPassword field.

Request Parameters

apiOperation  String =TOKENIZE FIXED

Existence
FIXED
Fixed value
TOKENIZE
Validation Rules
Any sequence of zero or more unicode characters.
XSD type
string

merchant  Alphanumeric + additional characters = COMPULSORY

Existence
COMPULSORY
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '%', '.'
XSD type
string
minimum length
1
maximum length
40

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
XSD type
string
minimum length
31
maximum length
35

token  Alphanumeric = COMPULSORY

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

apiOperation  String =TOKENIZE FIXED

Existence
FIXED
Fixed value
TOKENIZE
Validation Rules
Any sequence of zero or more unicode characters.
XSD type
string

billing   = OPTIONAL

Details of the payer's billing address.
Fixed value

billing.address   = OPTIONAL

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

billing.address.city  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

billing.address.company  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

billing.address.country  Upper case alphabetic text = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

billing.address.postcodeZip  Alphanumeric + additional characters = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'
XSD type
string
minimum length
1
maximum length
10

billing.address.stateProvince  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
20

billing.address.stateProvinceCode  String = OPTIONAL

Providing this field might improve your payer experience for 3-D Secure payer authentication.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
3

billing.address.street  String = OPTIONAL

For example, this may be the street name and number, or the Post Office Box details.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

billing.address.street2  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

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

customer   = OPTIONAL

Information about the customer, including their contact details.
Fixed value

customer.email  Email = OPTIONAL

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.
Existence
OPTIONAL
Fixed value
Validation Rules
Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses
XSD type
string

customer.firstName  String = OPTIONAL

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

customer.lastName  String = OPTIONAL

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

customer.mobilePhone  Telephone Number = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)
XSD type
string
mandatory country code
true
maximum total digits
15

customer.phone  Telephone Number = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)
XSD type
string
mandatory country code
true
maximum total digits
15

customer.taxRegistrationId  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
30

device   = OPTIONAL

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

device.ipAddress  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
7
maximum length
15

externalTokenProvider   = OPTIONAL

These fields are MANDATORY for MerchantLink merchants and must not contain sensitive data.
Fixed value

externalTokenProvider.customData  String = OPTIONAL

For example: '{"siteCode":"BNE"}'.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
4000

merchant  Alphanumeric + additional characters = COMPULSORY

Existence
COMPULSORY
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '%', '.'
XSD type
string
minimum length
1
maximum length
40

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
XSD 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
XSD 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
XSD type
string
minimum length
10
maximum length
10

shipping   = OPTIONAL

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

shipping.address   = OPTIONAL

The address to which this order will be shipped.
Fixed value

shipping.address.city  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

shipping.address.country  Upper case alphabetic text = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

shipping.address.postcodeZip  Alphanumeric + additional characters = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'
XSD type
string
minimum length
1
maximum length
10

shipping.address.stateProvince  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
20

shipping.address.street  String = OPTIONAL

For example, this may be the street name and number, or the Post Office Box details.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

shipping.address.street2  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

shipping.contact   = OPTIONAL

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

shipping.contact.firstName  String = OPTIONAL

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

shipping.contact.lastName  String = OPTIONAL

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

shipping.origin.postcodeZip  Alphanumeric + additional characters = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'
XSD type
string
minimum length
1
maximum length
10

sourceOfFunds   = OPTIONAL

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

posTerminal.serialNumber  ASCII Text = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data consists of ASCII characters
XSD type
string
minimum length
1
maximum length
16

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.ach   = OPTIONAL

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

sourceOfFunds.provided.ach.accountType  Enumeration = OPTIONAL

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

Existence
OPTIONAL
Fixed value
Validation Rules
XSD type
string
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  String = OPTIONAL

Retrieve this information from the payer.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
28

sourceOfFunds.provided.ach.bankAccountNumber  Alphanumeric + additional characters = OPTIONAL

Retrieve this information from the payer.
Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, ' ', '-', '/'
XSD type
string
minimum length
1
maximum length
17

sourceOfFunds.provided.ach.routingNumber  Digits = OPTIONAL

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.

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

sourceOfFunds.provided.ach.secCode  Enumeration = OPTIONAL

The SEC is defined by NACHA and describes the origin and intent of the payment. For details please refer to https://www.nacha.org/.
Existence
OPTIONAL
Fixed value
Validation Rules
XSD type
string
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   = OPTIONAL

Details as shown on the card.
Fixed value

sourceOfFunds.provided.card.expiry   = OPTIONAL

Expiry date, as shown on the card.
Fixed value

sourceOfFunds.provided.card.expiry.month  Digits = COMPULSORY

Months are numbered January=1, through to December=12.
Existence
COMPULSORY
Fixed value
Validation Rules
Data is a number between 1 and 12 represented as a string.
XSD type
string

sourceOfFunds.provided.card.expiry.year  Digits = COMPULSORY

The Common Era year is 2000 plus this value.
Existence
COMPULSORY
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
2
maximum length
2

sourceOfFunds.provided.card.nameOnCard  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
256

sourceOfFunds.provided.card.number  Digits = OPTIONAL

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

sourceOfFunds.provided.card.securityCode  Digits = OPTIONAL

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

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
XSD 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.
XSD 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.
XSD type
string
minimum length
4
maximum length
8

sourceOfFunds.provided.paypal   = OPTIONAL

Information about the payer's PayPal account.It is provided to you when the payer successfully makes a payment using PayPal or when you have established a billing agreement with the payer.
Fixed value

sourceOfFunds.provided.paypal.accountEmail  Email = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses
XSD type
string

sourceOfFunds.provided.paypal.accountHolder  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

sourceOfFunds.provided.paypal.billingAgreement   = OPTIONAL

Details about the agreement you have established with the payer that allows you to bill the payer's PayPal account for goods or services.
Fixed value

sourceOfFunds.provided.paypal.billingAgreement.cardinality  Enumeration = COMPULSORY

Existence
COMPULSORY
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
MULTIPLE
Indicates that you have multiple billing agreements with this payer. This means that a new agreement ID will be returned in response to each request.
SINGLE
Indicates that you have a single billing agreement with this payer. This means that the same agreement ID will be returned in response to each request.

sourceOfFunds.provided.paypal.billingAgreement.description  String = OPTIONAL

This description is displayed to the payer when they are asked to approve the billing agreement.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

sourceOfFunds.provided.paypal.billingAgreement.id  String = COMPULSORY

Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

sourceOfFunds.provided.paypal.billingAgreement.name  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

sourceOfFunds.provided.paypal.payerId  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
13

sourceOfFunds.provided.card.p2pe   = OPTIONAL

This holds the PAN in the case where it is encrypted by the terminal using DUKPT key exchange.
Fixed value

sourceOfFunds.provided.card.p2pe.cardBin  Digits = OPTIONAL

If you provide this, the gateway will check that the decrypted PAN has these leading six digits. If the check fails, the gateway will reject the transaction.

If you do not provided this, the gateway will not perform this check.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
1
maximum length
6

sourceOfFunds.provided.card.p2pe.encryptionState  String = OPTIONAL

INVALID means the terminal detected some form of error in the encryption process. The gateway will decline transactions with INVALID encryption state. This field may be omitted when the value is VALID.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
5
maximum length
7

sourceOfFunds.provided.card.p2pe.initializationVector  Hex = OPTIONAL

Omit this value if the terminal is not using an initialization vector to seed encryption.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is hexadecimal encoded
XSD type
string
minimum length
16
maximum length
16

sourceOfFunds.provided.card.p2pe.keySerialNumber  Hex = COMPULSORY

Existence
COMPULSORY
Fixed value
Validation Rules
Data is hexadecimal encoded
XSD type
string
minimum length
20
maximum length
20

sourceOfFunds.provided.card.p2pe.payload  Hex = COMPULSORY

Existence
COMPULSORY
Fixed value
Validation Rules
Data is hexadecimal encoded
XSD type
string
minimum length
32
maximum length
1024

sourceOfFunds.schemeTokenProvisioningIdentifier  ASCII Text = OPTIONAL

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.

Existence
OPTIONAL
Fixed value
Validation Rules
Data consists of ASCII characters
XSD type
string
minimum length
1
maximum length
64

sourceOfFunds.token  Alphanumeric = OPTIONAL

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.
Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
XSD type
string
minimum length
1
maximum length
40

sourceOfFunds.tokenRequestorID  Alphanumeric = OPTIONAL

This field is mandatory for payments where the Chase Pay wallet was used.
Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
XSD type
string
minimum length
11
maximum length
11

sourceOfFunds.type  Enumeration = COMPULSORY

If you are passing card data (in any form) on the API, then you need to set this value, and also provide the card details in the sourceOfFunds.provided.card group. In the case of digital wallets or device payment methods, you must also populate the order.walletProvider field.

If you are making a payment with a gateway token, then you can leave this field unset, and only populate the sourceOfFunds.token field. However you can set this to CARD if you want to overwrite or augment the token data with a card security code, expiry date, or cardholder name.
Existence
COMPULSORY
Fixed value
Validation Rules
XSD type
string
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.

token  Alphanumeric = COMPULSORY

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

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
XSD type
string
minimum length
3
maximum length
3

verificationStrategy  Enumeration = OPTIONAL

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.
Existence
OPTIONAL
Fixed value
Validation Rules
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.
XSD type
string
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 Parameters

result  Enumeration = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
XSD 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.

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.

Existence
Always Provided
Fixed value
Validation Rules
XSD 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.

billing   = CONDITIONAL

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

billing.address   = CONDITIONAL

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

billing.address.city  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

billing.address.company  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

billing.address.country  Upper case alphabetic text = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

billing.address.postcodeZip  Alphanumeric + additional characters = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'
XSD type
string
minimum length
1
maximum length
10

billing.address.stateProvince  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
20

billing.address.stateProvinceCode  String = CONDITIONAL

Providing this field might improve your payer experience for 3-D Secure payer authentication.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
3

billing.address.street  String = CONDITIONAL

For example, this may be the street name and number, or the Post Office Box details.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

billing.address.street2  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

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

customer   = CONDITIONAL

Information about the customer, including their contact details.
Fixed value

customer.email  Email = CONDITIONAL

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.
Existence
CONDITIONAL
Fixed value
Validation Rules
Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses
XSD type
string

customer.firstName  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
50

customer.lastName  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
50

customer.mobilePhone  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
20

customer.phone  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
20

customer.taxRegistrationId  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
30

device   = CONDITIONAL

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

device.ipAddress  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
7
maximum length
15

externalTokenProvider   = CONDITIONAL

These fields are MANDATORY for MerchantLink merchants and must not contain sensitive data.
Fixed value

externalTokenProvider.customData  String = CONDITIONAL

For example: '{"siteCode":"BNE"}'.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
4000

externalTokenProvider.responseCode  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

externalTokenProvider.responseMessage  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

replacementToken  Alphanumeric = CONDITIONAL

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

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
XSD type
string
minimum length
1
maximum length
16

response.gatewayCode  Enumeration = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
XSD 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_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  Enumeration = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
XSD 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

schemeToken   = CONDITIONAL

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

schemeToken.provider  Enumeration = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
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.tokenIdentifier  String = CONDITIONAL

The Mastercard Digital Enablement Service (MDES) calls this 'Token Unique Reference' (TUR).
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
64

shipping   = CONDITIONAL

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

shipping.address   = CONDITIONAL

The address to which this order will be shipped.
Fixed value

shipping.address.city  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

shipping.address.country  Upper case alphabetic text = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

shipping.address.postcodeZip  Alphanumeric + additional characters = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'
XSD type
string
minimum length
1
maximum length
10

shipping.address.stateProvince  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
20

shipping.address.street  String = CONDITIONAL

For example, this may be the street name and number, or the Post Office Box details.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

shipping.address.street2  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

shipping.contact   = CONDITIONAL

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

shipping.contact.firstName  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
50

shipping.contact.lastName  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
50

shipping.origin.postcodeZip  Alphanumeric + additional characters = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'
XSD type
string
minimum length
1
maximum length
10

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.ach   = CONDITIONAL

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

sourceOfFunds.provided.ach.accountIdentifier  String = CONDITIONAL

Retrieve this information from the payer.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
19
maximum length
27

sourceOfFunds.provided.ach.accountType  Enumeration = CONDITIONAL

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

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

Retrieve this information from the payer.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
28

sourceOfFunds.provided.ach.bankAccountNumber  Digits = CONDITIONAL

By default, the bank account number will be returned in a masked format, for example, xxxxxx0000. If you wish to return unmasked bank account numbers, you must have the requisite permission, set responseControls.sensitiveData, and authenticate your call to the API using certificate authentication. Contact your payment service provider for further information.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
9
maximum length
17

sourceOfFunds.provided.ach.routingNumber  Digits = CONDITIONAL

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.

Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
9
maximum length
9

sourceOfFunds.provided.ach.secCode  Enumeration = CONDITIONAL

The SEC is defined by NACHA and describes the origin and intent of the payment. For details please refer to https://www.nacha.org/.
Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
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   = CONDITIONAL

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).
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
XSD type
string
Value must be a member of the following list. The values are case sensitive.
MAESTRO
Maestro
MASTERCARD
MasterCard
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.
XSD 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
XSD 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.issuer  String = CONDITIONAL

WARNING: This information may be incorrect or incomplete – use at your own risk.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
0
maximum length
255

sourceOfFunds.provided.card.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
XSD type
string
minimum length
3
maximum length
50

sourceOfFunds.provided.card.nameOnCard  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
256

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
XSD 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
XSD type
string
Value must be a member of the following list. The values are case sensitive.
MASTERCARD
MasterCard
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
XSD 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.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
XSD 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
XSD 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
XSD type
string
minimum length
4
maximum length
8

sourceOfFunds.provided.paypal   = CONDITIONAL

It is provided to you when the payer successfully makes a payment using PayPal or when you have established a billing agreement with the payer.
Fixed value

sourceOfFunds.provided.paypal.accountEmail  Email = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses
XSD type
string

sourceOfFunds.provided.paypal.accountHolder  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

sourceOfFunds.provided.paypal.billingAgreement   = CONDITIONAL

Details about the agreement you have established with the payer that allows you to bill the payer's PayPal account for goods or services.
Fixed value

sourceOfFunds.provided.paypal.billingAgreement.cardinality  Enumeration = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
MULTIPLE
Indicates that you have multiple billing agreements with this payer. This means that a new agreement ID will be returned in response to each request.
SINGLE
Indicates that you have a single billing agreement with this payer. This means that the same agreement ID will be returned in response to each request.

sourceOfFunds.provided.paypal.billingAgreement.description  String = CONDITIONAL

This description is displayed to the payer when they are asked to approve the billing agreement.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

sourceOfFunds.provided.paypal.billingAgreement.id  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

sourceOfFunds.provided.paypal.billingAgreement.name  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

sourceOfFunds.provided.paypal.payerId  String = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
13

sourceOfFunds.schemeTokenProvisioningIdentifier  ASCII Text = CONDITIONAL

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.

Existence
CONDITIONAL
Fixed value
Validation Rules
Data consists of ASCII characters
XSD type
string
minimum length
1
maximum length
64

sourceOfFunds.type  Enumeration = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
XSD 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.

status  Enumeration = Always Provided

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.

Existence
Always Provided
Fixed value
Validation Rules
XSD 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

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.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
XSD type
string
minimum length
1
maximum length
40

usage   = CONDITIONAL

Information about the usage of 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"
XSD 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, '-', '_', ' ', '&', '+', '!', '$', '%', '.'
XSD 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"
XSD type
string

verificationStrategy  Enumeration = CONDITIONAL

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.
Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
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.

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
XSD 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
XSD 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
XSD 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
XSD 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
XSD 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
XSD 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 © 2022 UniCredit Bank