PCI/Charge/Authenticate (PCI)
Expert mode integration
Reference documentation, to see how to integrate it, it's here: Bearer authentication service (expert mode)
Input parameters
amount
Amount of the transaction to authenticate. Its value must be positive and in the smallest currency unit.
Example: 30050 for EUR 300.50.
Format
currency
Currency of the transaction to authenticate. Alphabetic code in uppercase in accordance with the ISO 4217 standard (e.g.: “EUR” for euro).
Format
transactionCategory
Transaction category. Is usually set to PAYMENT for a regular payment.
Possible values
| Values | Description |
|---|---|
| ADD_CARD | Addition of a card to a wallet. |
| PAYMENT | Regular payment (includes recurring or installment payments). |
Format
productType
Product type for which the transaction is made.
Possible values
| Values | Description |
|---|---|
| ACCOUNT_FUNDING | Wire transfer to an account. |
| CHECK_ACCEPTANCE | Acceptance testing. |
| GOODS_OR_SERVICE_PURCHASE | Payment for an item or a service. Value used if the field is not transmitted in the request. |
| PREPAID_ACTIVATION_AND_LOAD | Activation and loading of a prepaid card. |
| QUASI_CASH_TRANSACTION | Transactions in cash equivalents (e.g.: holiday coupons, lottery tickets, etc.). |
Format
merchant.name
Merchant's name.
Format
merchant.mid
Merchant ID number.
Format
merchant.tid
Terminal ID. Point of sale identifier defined on the acceptance contract.
This field is only used in Colombia for choosing between REDEBAN and CREDIBANCO.
Format
merchant.mcc
Specific code on the DS indicates the type of activity, product or service of the vehicle. (Merchant Category Code = MCC)
Format
networkPreference
Path: paymentForm.networkPreference
Name of the preferred network recommended by the merchant.
Possible values
| value | Description |
|---|---|
| AMEX | American Express network (SafeKey) |
| CB | Bank Card Network |
| MASTERCARD | MasterCard network |
| VISA | Visa network |
| ELO | Elo network (Brazil) |
| DINERS | Diners network |
| DISCOVER | Discover network |
| OSB | Network OSB |
Format
accountType
Path: paymentForm.accountType
Card type. This field is mandatory in Brazil.
Possible values
| Values | Description |
|---|---|
| DEBIT | Debit card |
| CREDIT | Credit card |
Format
paymentForm.pan
PAN (Primary Account Number) is the primary card number usually consisting of 16 digits.
Format
expiryMonth
Path: paymentForm.expiryMonth
Expiration month in a two-digit format. Example: "09" for September.
Format
expiryYear
Path: paymentForm.expiryYear
Expiration year in a two-digit format. Example: "25" for 2025.
Format
cardHolderName
Path: paymentForm.cardHolderName
Cardholder's first and last names.
Format
installmentNumber
Path: paymentForm.installmentNumber
Number of installments.
Format
customer.reference
Buyer ID on the merchant side.
Format
customer.email
Buyer's e-mail address.
- Email structure specifications: RFC-2822
Format
address
Path: customer.billingDetails.address
Billing address.
Warning: the characters > and < are not authorized.
Format
address2
Path: customer.billingDetails.address2
Second line of the billing address.
Warning: the characters > and < are not authorized.
Format
category
Path: customer.billingDetails.category
Buyer type.
Format
Possible values
| Values | Description |
|---|---|
| PRIVATE | Individual buyer type. |
| COMPANY | Company buyer type. |
cellPhoneNumber
Path: customer.billingDetails.cellPhoneNumber
Buyer's cell phone number.
Accepts all formats:
Examples:
- 0623456789
- +33623456789
- 0033623456789
- (+34) 824 65 43 21
- 87 77 12 34
Format
city
Path: customer.billingDetails.city
City of the billing address.
Format
country
Path: customer.billingDetails.country
Buyer's country (in uppercase, in accordance with the ISO 3166-1 alpha-2 country codes).
Format
Possible values
Examples of possible values:
| Country | Code |
|---|---|
| AUSTRIA | AT |
| BRAZIL | BR |
| CORSICA | FR |
| IVORY COAST | CI |
| FRANCE | FR |
| GUADELOUPE | GP |
| INDIA | IN |
| MARTINIQUE | MQ |
| NEW CALEDONIA | NC |
| ST-PIERRE-ET-MIQUELON | PM |
| FRENCH POLYNESIA | PF |
district
Path: customer.billingDetails.district
District of the billing address.
Format
firstName
Path: customer.billingDetails.firstName
Buyer's first name.
Format
identityCode
Path: customer.billingDetails.identityCode
National identifier. Allows to identify each citizen within a country.
Format
identityType
Path: customer.billingDetails.identityType
ID type.
Format
language
Path: customer.billingDetails.language
Buyer's language code, according to ISO 639-1.
Specify the language in which payment confirmation e-mails are sent.
Format
Possible values
Examples of possible values:
| Language | Code |
|---|---|
| German (Germany) | DE |
| English (United Kingdom) | EN |
| English (United States) | EN |
| Chinese (Traditional) | ZH |
| Spanish (Spain) | ES |
| Spanish (Chile) | ES |
| French (France) | FR |
| Italian (Italy) | IT |
| Japanese (Japan) | JP |
| Dutch (the Netherlands) | NL |
| Polish (Poland) | PL |
| Portuguese (Brazil) | PT |
| Portuguese (Portugal) | PT |
| Russian (Russia) | RU |
lastName
Path: customer.billingDetails.lastName
Buyer's last name.
Format
legalName
Path: customer.billingDetails.legalName
Legal name.
Format
phoneNumber
Path: customer.billingDetails.phoneNumber
Buyer's phone number.
Accepts all formats:
Examples:
- 0123456789
- +33123456789
- 0033123456789
- (00.571) 638.14.00
- 40 41 42 42
Format
state
Path: customer.billingDetails.state
Region (state) of the billing address. It is recommended, but not mandatory, to pass the value in ISO-3166-2.
Format
streetNumber
Path: customer.billingDetails.streetNumber
Street number of the billing address.
Accepted characters:
- Alphabetical characters (from "A" to "Z" and from "a" to "z")
- Space
Format
title
Path: customer.billingDetails.title
Buyer's title.
Examples:
- Mr
- Ms.
- Mrs
Format
zipCode
Path: customer.billingDetails.zipCode
Zip code of the billing address.
Format
address
Path: customer.shippingDetails.address
Shipping address.
Warning: the characters > and < are not authorized.
Format
address2
Path: customer.shippingDetails.address2
Second line of the shipping address.
Warning: the characters > and < are not authorized.
Format
category
Path: customer.shippingDetails.category
Buyer type.
Format
Possible values
| Values | Description |
|---|---|
| PRIVATE | Individual buyer type. |
| COMPANY | Company buyer type. |
city
Path: customer.shippingDetails.city
Shipping city.
Format
country
Path: customer.shippingDetails.country
Shipping country (in uppercase, in accordance with the ISO 3166-1 alpha-2 country codes).
Format
Possible values
Examples of possible values:
| Country | Code |
|---|---|
| AUSTRIA | AT |
| BRAZIL | BR |
| CORSICA | FR |
| IVORY COAST | CI |
| FRANCE | FR |
| GUADELOUPE | GP |
| INDIA | IN |
| MARTINIQUE | MQ |
| NEW CALEDONIA | NC |
| ST-PIERRE-ET-MIQUELON | PM |
| FRENCH POLYNESIA | PF |
deliveryCompanyName
Path: customer.shippingDetails.deliveryCompanyName
Name of the delivery company.
Format
district
Path: customer.shippingDetails.district
District of the billing address.
Format
firstName
Path: customer.shippingDetails.firstName
First name of the recipient.
Format
identityCode
Path: customer.shippingDetails.identityCode
National identifier. Allows to identify each citizen within a country.
Format
lastName
Path: customer.shippingDetails.lastName
Buyer's last name.
Format
legalName
Path: customer.shippingDetails.legalName
Legal name in case of shipping to a company.
Format
phoneNumber
Path: customer.shippingDetails.phoneNumber
Buyer's phone number.
Accepts all formats:
Examples:
- 0123456789
- +33123456789
- 0033123456789
- (00.571) 638.14.00
- 40 41 42 42
Format
shippingMethod
Path: customer.shippingDetails.shippingMethod
Shipping mode.
Format
Possible values
| value | Description |
|---|---|
| RECLAIM_IN_SHOP | Item pickup at the shop. |
| RELAY_POINT | Use of a third-party pickup network (Kiala, Alveol, etc.). |
| RECLAIM_IN_STATION | Pickup at an airport, a train station or a travel agency. |
| PACKAGE_DELIVERY_COMPANY | Shipping by the transporter (Colissimo, UPS, etc.). |
| ETICKET | Issue of an electronic ticket, online download of the product. |
| CARD_HOLDER_ADDRESS | Delivery to the buyer. Reserved for future use. |
| VERIFIED_ADDRESS | Delivery to a verified address.Reserved for future use. |
| NOT_VERIFIED_ADDRESS | Delivery to a non-verified address.Reserved for future use. |
| SHIP_TO_STORE | In-store pickup.Reserved for future use. |
| DIGITAL_GOOD | Digital delivery.Reserved for future use. |
| ETRAVEL_OR_ETICKET | E-ticket.Reserved for future use. |
| OTHER | Other: Reserved for future use. |
| PICKUP_POINT | Pickup point delivery.Reserved for future use. |
| AUTOMATED_PICKUP_POINT | Pickup at an automatic pickup point.Reserved for future use. |
shippingSpeed
Path: customer.shippingDetails.shippingSpeed
Shipping delay.
Format
Possible values
Examples of possible values:
| value | Description |
|---|---|
| STANDARD | Standard shipping. |
| EXPRESS | Express shipping (in less than 24h). |
| PRIORITY | Priority shipping (Click & Collect). |
state
Path: customer.shippingDetails.state
Region of the billing address.
Format
streetNumber
Path: customer.shippingDetails.streetNumber
Street number of the delivery address.
Accepted characters:
- Alphabetical characters (from "A" to "Z" and from "a" to "z")
- Space
Format
zipCode
Path: customer.shippingDetails.zipCode
Zip code of the billing address.
Format
insuranceAmount
Path: customer.shoppingCart.insuranceAmount
Insurance amount for the entire order, expressed in the smallest monetary unit (cent for euro).
Example: 30050 for EUR 300.50.
Format
shippingAmount
Path: customer.shoppingCart.shippingAmount
Amount of delivery fees for the entire order, expressed in its smallest monetary unit (cent for euro).
Example: 30050 for EUR 300.50.
Format
taxAmount
Path: customer.shoppingCart.taxAmount
Amount of taxes for the entire order expressed in the smallest monetary unit (cent for euro).
Example: 30050 for EUR 300.50.
Format
cartItemInfo
Path: customer.shoppingCart.cartItemInfo
cardItemInfo is a list that contains Customer/ShoppingCartItemInfo objects.
It allows you to describe each item in the cart.
Format
productAmount
Path: customer.shoppingCart.cartItemInfo.productAmount
Amount of the product expressed in the smallest currency unit (cent for euro).
Example: 30050 for EUR 300.50.
Format
productLabel
Path: customer.shoppingCart.cartItemInfo.productLabel
Product name.
Format
productQty
Path: customer.shoppingCart.cartItemInfo.productQty
Product quantity.
Format
productRef
Path: customer.shoppingCart.cartItemInfo.productRef
Product reference.
Format
productType
Path: customer.shoppingCart.cartItemInfo.productType
Product type.
Possible values
| value | Description |
|---|---|
| FOOD_AND_GROCERY | Food and grocery |
| AUTOMOTIVE | Cars / Moto |
| ENTERTAINMENT | Entertainment / Culture |
| HOME_AND_GARDEN | Home and gardening |
| HOME_APPLIANCE | Household appliances |
| AUCTION_AND_GROUP_BUYING | Auctions and group purchasing |
| FLOWERS_AND_GIFTS | Flowers and presents |
| COMPUTER_AND_SOFTWARE | Computers and software |
| HEALTH_AND_BEAUTY | Health and beauty |
| SERVICE_FOR_INDIVIDUAL | Services for individuals |
| SERVICE_FOR_BUSINESS | Services for companies |
| SPORTS | Sports |
| CLOTHING_AND_ACCESSORIES | Clothes and accessories |
| TRAVEL | Travel |
| HOME_AUDIO_PHOTO_VIDEO | Sound, image and video |
| TELEPHONY | Telephony |
Format
productVat
Path: customer.shoppingCart.cartItemInfo.productVat
Product type.
Tax fee amount (expressed in the smallest currency unit).
Possible values
| value | Description |
|---|---|
| integer | Transaction amount. Its value must be a positive integer (e.g.: 1234 for 12.34 EUR). |
| Decimal number, lower than 100 | Percentage applied to the amount. Examples: 20.0 or 19.6532 |
To display a percentage applied to the payment amount for the product in question, the value should have maximum 4 digits after the decimal point. The decimal separator is mandatory for displaying a percentage. The decimal separator is represented by the "." symbol.
Format
device.deviceType
Type of device on which the authentication takes place.
Possible values
| value | Description |
|---|---|
| BROWSER | Authentication in a browser. |
Format
device.acceptHeader
Exact content of the Accept HTTP header as it is sent by the Buyer’s browser.
Format
device.userAgent
Exact content of the HTTP "user-agent" header sent by the browser. Must be truncated if the value exceeds 2048 characters.
Obtained from the client’s browser via the “navigator.userAgent” property.
JavaScript code allowing to retrieve the value:
const language = navigator.userAgent;
Format
device.ip
Browser’s IP address as returned in HTTP headers by the client. IPV4 format (e.g.: 1.12.123.255) or IPV6 (e.g.: 2011:0db8:85a3:0101:0101:8a2e:0370:7334). Variable length, maximum 45 characters.
Format
device.javaEnabled
Boolean that represents the browser's capacity to execute Java.The value is the one returned by the “navigator.javaEnabled()” function, it can be true or false.
JavaScript code allowing to retrieve the value:
const javaEnabled = navigator.javaEnabled();
Format
device.language
Obtained from the client browser via the "navigator.language" property.
Examples: “en”, “en-US”, “de”, “fr”, etc.
JavaScript code allowing to retrieve the value:
const language = navigator.language;
Format
device.colorDepth
Value representing the depth of the color palette used to display images, in bits per pixel.
Obtained from the client’s browser via the “screen.colorDepth” property.
JavaScript code allowing to retrieve the value:
const colorDepth = screen.colorDepth;
Format
device.screenHeight
The total height of the client's screen in pixels. The value is the one returned by the "screen.height" property. From 1 to 6 characters.
JavaScript code allowing to retrieve the value:
const screenHeight = screen.height;
Format
device.screenWidth
The total width of the client's screen in pixels. The value is the one returned by the "screen.width" property. From 1 to 6 characters.
JavaScript code allowing to retrieve the value:
const screenWidth = screen.width;
Format
timeZoneOffset
Path: device.timeZoneOffset
Time difference between UTC time and the local time of the client browser, in minutes. Its value is -120 for a user in the UTC+2 time zone and 570 for the UTC-09:30 time zone.
JavaScript code allowing to retrieve the value:
const timeZoneOffset = new Date().getTimezoneOffset();
Format
id
Unique identifier of the authentication, in UUID format.
Null upon the first call.
When multiple calls to the PCI/Charge/Authenticate Web Service are required to perform a buyer authentication, the value of the ID transmitted must be the same for each call of the same authentication. In this case, the ID provided in the previous response must be used.
Format
name
Path: instructionResult.name
Instruction name.
Possible values
| value | Description |
|---|---|
| CHALLENGE | Challenge Instruction that allows interactive user authentication via the ACS. |
| FINGERPRINT | Fingerprint Instruction that allows to identify the user via the ACS. |
Format
value
Path: instructionResult.value
Result as a JWT string, or a plain text error code in case of an error (timeout for example).
Format
challengePreference
Path: instructionResult.protocol.challengePreference
Indicates whether or not the Merchant has requested a challenge.
Possible values
| value | 3DS2 card | |
|---|---|---|
| NO_PREFERENCE | The choice of preference is delegated to the card issuer. | |
| NO_CHALLENGE_REQUESTED | Allows to request an authentication without interaction (frictionless). | |
| CHALLENGE_REQUESTED | Allows you to request strong authentication for the transaction. | |
| CHALLENGE_MANDATED | Allows to indicate that, for regulatory reasons, strong authentication is required for the transaction. | |
| DATA_ONLY | Allows you to request authentication without interaction, processed by the DS instead of the ACS of the issuing bank.The transaction cannot benefit from the liability shiftThe authentication will be disabled if the network does not support this feature. The PCI/Charge/Authenticate service returns an INT_808 error code if the fieldtransactionCategoryis not valued atPAYMENT. |
Format
name
Path: instructionResult.protocol.name
Name of the protocol used by the cardholder authentication services.
Possible values
| value | Description |
|---|---|
| THREEDS | 3D Secure protocol |
Format
network
Path: instructionResult.protocol.network
Network where the payment method was authenticated.
This field is obligatoire for the management of the timeout on the 3ds method, when the instructionResult.value field is set to TIMEOUT.
Currently supported networks
| value |
|---|
| CB |
| VISA |
| MASTERCARD |
| AMEX_SAFEKEY |
| PROTECTBUY |
Format
simulation
Path: instructionResult.protocol.simulation
Boolean that indicates if the authentication must be done in simulation mode. If you set this mandatory field to:
true, you activate the simulation mode.false, you do not enable the simulation mode.
This mode allows you to perform a merchant integration without being in production mode, and without using real cards.
Format
version
Path: instructionResult.protocol.version
Version of the protocol used by the cardholder authentication services.
Currently supported versions
| value | Description |
|---|---|
| 1.0.2 | Version 1.0.2 |
| 2.1.0 | Version 2.1.0 |
| 2.2.0 | Version 2.2.0 |
Format
protocolRequest.name
Name of the protocol used by the cardholder authentication services.
Possible values
| value | Description |
|---|---|
| THREEDS | 3D Secure protocol |
Format
version
Path: protocolRequest.version
Allows you to force the version of the authentication protocol to be used.
Currently supported versions
| value | Description |
|---|---|
| 2 | 3D Secure 2 |
Format
challengePreference
Path: protocolRequest.challengePreference
Indicates whether or not the Merchant has requested a challenge.
Possible values
| value | 3DS2 card | |
|---|---|---|
| NO_PREFERENCE | The choice of preference is delegated to the card issuer. | |
| NO_CHALLENGE_REQUESTED | Allows to request an authentication without interaction (frictionless). | |
| CHALLENGE_REQUESTED | Allows you to request strong authentication for the transaction. | |
| CHALLENGE_MANDATED | Allows to indicate that, for regulatory reasons, strong authentication is required for the transaction. | |
| DATA_ONLY | Allows you to request authentication without interaction, processed by the DS instead of the ACS of the issuing bank.The transaction cannot benefit from the liability shiftThe authentication will be disabled if the network does not support this feature. The PCI/Charge/Authenticate service returns an INT_808 error code if the fieldtransactionCategoryis not valued atPAYMENT. |
Format
recurring.expiryDate
Recurring payment expiry date. Example: 12/24/2019
Format
unit
Path: recurring.frequency.unit
Recurring payment frequency.
Possible values
| Values | Description |
|---|---|
| DAY | In days |
| MONTH | In months |
| YEAR | In years |
Format
value
Path: recurring.frequency.value
Value of the recurring payment frequency, expressed in unit of frequency. Example: 12.
Format
Response reference
Several responses are possible, depending on the context:
| Response | Context |
|---|---|
| AuthenticationResponseData | Object containing the authentication result. |
See the reference of each response for more information.