PCI/Charge/Authenticate (PCI)
You can find the reference documentation on its integration here: Cardholder authentication service
Request parameters
amount
Amount of the transaction to authenticate. Its value must be positive and in the smallest currency unit (cent for euro). E.g.: 1234 for 12.34 EUR
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.
Format
Possible values
| values | DESCRIPTION |
|---|---|
| ADD_CARD | Addition of a card to a wallet. |
| PAYMENT | Regular payment (includes recurring or installment payments). |
productType
Product type for which the transaction is made This field is required .
Possible values
| values | DESCRIPTION |
|---|---|
| ACCOUNT_FUNDING | Wire transfer to an account. |
| CHECK_ACCEPTANCE | Acceptance testing. |
| GOODS_OR_SERVICE_PURCHASE | Purchase of an item or a service. |
| 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.mid
Merchant ID number.
Format
merchant.tid
Terminal ID POS identifier defined within the acceptance contract.
This field is only used in Colombia for choosing between REDEBAN and CREDIBANCO.
Format
networkPreference
Path: paymentForm.networkPreference
Name of the network recommended by the Merchant in case of multi-brand cards (e.g.: CB and VISA within the same card).
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
Expiry month.
Format
expiryYear
Path: paymentForm.expiryYear
Expiry year.
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.
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
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.
See the customer.shoppingCart.* properties for more information.
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.
Format
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 |
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.
device.deviceType
Type of device on which the authentication takes place.
Several methods can be used to identify the device type (screen size, user-agent, etc.).
Example of JavaScript code based on the screen size:
var isMobile = "";
var testMobile = window.matchMedia("only screen and (max-width: 760px)");
if (testMobile.matches){
isMobile="MOBILE";
}
else{
isMobile="BROWSER"
}
Possible values
| Value | DESCRIPTION |
|---|---|
| BROWSER | Authentication in a browser. |
| MOBILE | Authentication by phone. |
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
Total height of the client's screen in pixels. La valeur est celle retournée par la propriété "screen height".De 1 à 6 caractères
JavaScript code allowing to retrieve the value:
const screenHeight = screen.height;
Format
device.screenWidth
The total width of the client’s screen in pixels. La valeur est celle retournée par la propriété "screen width".De 1 à 6 caractères
JavaScript code allowing to retrieve the value:
const screenWidth = screen.width;
Format
timeZoneOffset
Path: device.timeZoneOffset
Timezone difference between UTC and the local time of the Buyer’s 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 several calls to the PCI/Charge/Authenticate Web Service are required to perform buyer authentication, the value of the transmitted ID must be the same for each call within the same authentication. Then, 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 in the form of JWT string, or an error code in plain text format in case of error ( timeout for example).
Format
challengePreference
Path: instructionResult.protocol.challengePreference
Indicates whether or not the Merchant has requested a challenge.
Possible values
| Value | 3DS1 card | 3DS2 card | |
|---|---|---|---|
| NO_PREFERENCE | Forced 3DS1 authentication. | The choice of preference is delegated to the card issuer. | |
| NO_CHALLENGE_REQUESTED | Disabled 3DS1 authentication. | Allows you to request authentication without interaction (frictionless). | |
| CHALLENGE_REQUESTED | Forced 3DS1 authentication. | Allows you to request strong authentication for the transaction. | |
| CHALLENGE_MANDATED | Forced 3DS1 authentication. | Allows to indicate that, for regulatory reasons, strong authentication is required for the transaction. |
Format
name
Path: instructionResult.protocol.name
Name of the protocol used by the cardholder authentication services.
Possible values
| Value | DESCRIPTION |
|---|---|
| THREEDS | 3D Secure protocol |
| PROCESOS_DINERS | Procesos Diners OTP protocol |
| OSB | Protocol OTP OSB |
Format
network
Path: instructionResult.protocol.network
Name of the network recommended by the Merchant in case of multi-brand cards (e.g.: CB and VISA within the same card).
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
simulation
Path: instructionResult.protocol.simulation
Boolean indicating if the authentication must be carried out in simulation mode. Simulation mode allows to perform merchant integration without being in production or using a real card.
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 |
Format
protocolRequest.name
Name of the protocol used by the cardholder authentication services.
Possible values
| Value | DESCRIPTION |
|---|---|
| THREEDS | 3D Secure protocol |
| PROCESOS_DINERS | Procesos Diners OTP protocol |
| OSB | Protocol OTP OSB |
Format
version
Path: protocolRequest.version
Allows you to force the version of the authentication protocol to be used.
Currently supported versions
| Value | DESCRIPTION |
|---|---|
| 1 | 3D Secure 1 |
| 2 | 3D Secure 2 |
Format
challengePreference
Path: protocolRequest.challengePreference
Indicates whether or not the Merchant has requested a challenge.
Possible values
| Value | 3DS1 card | 3DS2 card | |
|---|---|---|---|
| NO_PREFERENCE | Forced 3DS1 authentication. | The choice of preference is delegated to the card issuer. | |
| NO_CHALLENGE_REQUESTED | Disabled 3DS1 authentication. | Allows you to request authentication without interaction (frictionless). | |
| CHALLENGE_REQUESTED | Forced 3DS1 authentication. | Allows you to request strong authentication for the transaction. | |
| CHALLENGE_MANDATED | Forced 3DS1 authentication. | Allows to indicate that, for regulatory reasons, strong authentication is required for the transaction. |
Format
recurring.expiryDate
Date d'expiration de la récurrence. Exemple: 2019-12-24
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.