support
Back to documentation
Search
Categories
Tags
main parametersexpand all
amount
required
currency
required
orderId
recommended
formAction
paymentForms
[1]
paymentMethodType
required
pan
Test Cards

    No FormToken defined

    PanDescriptionStatus3DS3DS2
    required
    expiryMonth
    required
    expiryYear
    required
    securityCode
    brand
    installmentNumber
    firstInstallmentDelay
    overridePaymentCinematic
    paymentMethodToken
    cardHolderName
    identityDocumentNumber
    identityDocumentType
    taxAmount
    taxRate
    Device information
    device
    deviceType
    required
    acceptHeader
    required
    userAgent
    required
    ip
    javaEnabled
    required
    language
    required
    colorDepth
    required
    screenHeight
    required
    screenWidth
    required
    timeZoneOffset
    required
    information about your customer
    customer
    reference
    recommended
    email
    recommended
    billingDetails
    title
    category
    firstName
    lastName
    phoneNumber
    streetNumber
    address
    address2
    district
    zipCode
    city
    state
    country
    language
    cellPhoneNumber
    identityCode
    identityType
    legalName
    shippingDetails
    category
    firstName
    lastName
    phoneNumber
    streetNumber
    address
    address2
    district
    zipCode
    city
    state
    country
    deliveryCompanyName
    shippingSpeed
    shippingMethod
    legalName
    identityCode
    shoppingCart
    insuranceAmount
    shippingAmount
    taxAmount
    cartItemInfo
    [1]
    productLabel
    productType
    productRef
    productQty
    productAmount
    productVat
    ipAddress
    general transaction options
    acquirerTransientData
    [1]
    :
    contrib
    ipnTargetUrl
    fingerPrintId
    metadata
    [1]
    :
    merchantPostUrlRefused
    merchantPostUrlSuccess
    strongAuthentication
    card related options
    transactionOptions
    cardOptions
    paymentSource
    mid
    manualValidation
    captureDelay
    retry
    debitCreditSelector
    information about the sub-merchant
    subMerchantDetails
    companyType
    legalNumber
    name
    required
    url
    phoneNumber
    address1
    address2
    zip
    city
    country
    mcc
    mid
    softDescriptor
    state
    facilitatorId
    External authentication data
    authenticationDetails
    protocol
    name
    required
    version
    required
    directoryServer
    challengePreference
    authenticationType
    status
    required
    commerceIndicator
    authenticationValue
    dsScore
    authValueAlgorithm
    requestorName
    required
    dsTransID
    acsTransID
    xid
    exemption
    challengeCancelationIndicator
    transactionStatusReason
    3DS response parameters
    instructionResult
    name
    required
    value
    required
    protocol
    name
    required
    version
    required
    network
    required
    challengePreference
    required
    simulation
    required
    operationSessionId
    new properties
    useCase
    Try me
    Documentation

    PCI/Charge/CreatePayment

    POSThttps://api.systempay.fr/api-payment/V4/PCI/Charge/CreatePayment

    The activation of these features is subject to prior approval by Systempay.

    The Charge/CreatePayment operation is a REST API Web Service. It allows to create a new transaction using a card number.

    In PCI-DSS mode, you can directly fill in card details in the web service.

    For non-PCI use with embedded form, go here: Charge/CreatePayment(non-PCI).

    Authentication with our authentication server

    This Web Service allows to make a 3DS transaction. It is therefore necessary to know how this functionality works. To see how to integrate it, the reference documentation is present here: PCI Payment Creation Web Service.

    Important aspect related to CB payments

    With the implementation of PSD2, issuers can refuse the transaction if 3D Secure authentication has not been performed. This behavior is called "Soft Decline".

    In the case of a "Soft Decline" the transactionDetails.cardDetails.authorizationResponse.authorizationResult field is valued at 81. It is the responsibility of the merchant to initiate a new payment with 3D secure authentication.

    Authentication with another authentication server

    The PCI/Charge/CreatePayment service allows PCI-DSS merchants who have performed cardholder authentication via their own authentication servers to create a payment method alias by passing card information as well as cardholder authentication data in their request.

    See the integration guide for more information.

    Request parameters

    The PCI/Charge/CreatePayment REST Web Service supports the following parameters:

    amount

    Payment amount in its smallest currency unit (cent for euro).

    Example: 30050 for EUR 300.50.

    Format

    currency

    Payment currency. Alphabetic code in uppercase according to alpha-3 (ISO 4217).

    Eg: "EUR" for the euro.

    Format

    Possible values

    The possible values are:

    Currency ISO 4217 ENCODING Fractional unit
    Australian dollar (036) AUD 2
    Lev Bulgare (975) BGN 2
    Brazilian real (986) BRL 2
    Canadian dollar (124) CAD 2
    Swiss franc (756) CHF 2
    Chinese renminbi (156) CNY 1
    Czech koruna (203) CZK 2
    Danish crown (208) DKK 2
    Euro (978) EUR 2
    Pound Sterling (826) GBP 2
    Hong Kong dollar (344) HKD 2
    Kuna Croate (191) HRK 2
    Hungarian forint (348) HUF 2
    Indian rupee (356) INR 2
    Indonesian rupiah (360) IDR 2
    Japanese yen (392) JPY 0
    Cambodian riel (116) KHR 0
    South Korean won (410) KRW 0
    Mexican peso (484) MXN 2
    Malaysian ringgit (458) MYR 2
    New Zealand dollar (554) NZD 2
    Norwegian crown (578) NOK 2
    Philippine peso (608) PHP 2
    Polish zloty (985) PLN 2
    Leu Roumain (946) RON 2
    Russian ruble (643) RUB 2
    Singapore dollar (702) SGD 2
    Swedish krona (752) SEK 2
    Thai baht (764) THB 2
    Turkish lira (949) TRY 2
    New Taiwan dollar (901) TWD 2
    US dollar (840) USD 2
    CFP Franc (953) XPF 0
    South African rand (710) ZAR 2

    orderId

    Order reference defined by the Merchant.Does not support UTF-8 characters.

    Format

    formAction

    formAction allows you to define the type of desired behavior when creating the transaction.

    Format

    Possible values

    The possible values are:

    Value Description
    PAYMENT Creating a simple transaction. Default behavior.
    REGISTER_PAY Creation of an alias (token) of the payment method at the same time as the transaction. Does not allow the creation of an alias associated with an IBAN.
    null If the value is null or undefined, PAYMENT is applied.

    PAYMENT:

    The web service will return a formToken.

    This is the default behavior. The call to Charge/CreatePayment creates a transaction without performing any additional operations.

    REGISTER_PAY:

    The web service will return a formToken.

    A payment method token is created simultaneously with the transaction. This token will then allow you to create one-click transactions. The newly created token will be specified in the paymentMethodToken property. For more information, see the article dedicated to Creating and using tokens.

    paymentMethodType

    Path: paymentForms.paymentMethodType

    Type of payment method.

    Possible values

    Value Description
    CARD Card payment.
    SDD SEPA Direct Debit

    Format

    paymentForms.pan

    PAN (Primary Account Number) is the primary card number usually consisting of 16 digits.

    Format

    expiryMonth

    Path: paymentForms.expiryMonth

    Expiration month in a two-digit format. Example: "09" for September.

    Format

    expiryYear

    Path: paymentForms.expiryYear

    Expiration year in a two-digit format. Example: "25" for 2025.

    Format

    securityCode

    Path: paymentForms.securityCode

    Card security code.

    Its length can vary between 3 or 4 digits depending on the card type.

    Format

    paymentForms.brand

    Card brand.

    Format

    WARNING: the threeDSResponse object will soon become deprecated. It may be null or absent in future releases. It is recommended to use transactions[0].transactionDetails.cardDetails.authenticationResponse.

    cardHolderName

    Path: paymentForms.cardHolderName

    Cardholder's first and last names.

    Format

    firstInstallmentDelay

    Path: paymentForms.firstInstallmentDelay

    Number of deferred months to be applied to the first installment of payment in installments. Field specific to acquirers in Latin America.

    Format

    identityDocumentNumber

    Path: paymentForms.identityDocumentNumber

    Buyer's ID number.

    The format depends on the ID type: between 7 and 13 characters, digits, letters and/or dots.

    In Latin America, this parameter may be mandatory for some buyers.

    Format

    identityDocumentType

    Path: paymentForms.identityDocumentType

    ID type.

    Possible values:

    Type Description
    DNI Documento Nacional de Identidad
    CC Cédula de ciudadania
    TI Tarjeta de Identidad
    CE Cédula de Extranjeria
    NI Número de Identificación Tributaria
    PS Pasaporte

    Format

    installmentNumber

    Path: paymentForms.installmentNumber

    Number of installments.

    Format

    paymentForms.mid

    Merchant ID number. If this field is populated, make sure you use the appropriate MID depending on the card scheme.

    Format

    overridePaymentCinematic

    Path: paymentForms.overridePaymentCinematic

    Allows you to change the capture mode. Specific to Latin American purchasers. This feature is not available in Colombia.

    Possible values:

    Value Description
    IMMEDIATE_CAPTURE Immediate capture scenario: the capture is triggered by the acquirer on the day of payment.
    DELAYED_CAPTURE Deferred capture process: the capture is triggered by the payment gateway, always before the authorization request expiry.

    Format

    paymentMethodToken

    Path: paymentForms.paymentMethodToken

    Token associated with a payment method.

    Only tokens associated with a credit card are supported.

    Format

    taxAmount

    Amount of taxes for the entire order expressed in the smallest monetary unit (cent for euro).

    Example: 30050 for EUR 300.50.

    Format

    taxRate

    Used by some payment methods in Latin America. Allows you to transmit the tax rate applied to the entire order. The value must be the percentage to apply (21 for 21%).

    Format

    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"
    	}

    The device object and its attributes are not required if paymentSource is set to MOTO.

    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.

    The device object and its attributes are not required if paymentSource is set to MOTO.

    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;

    The device object and its attributes are not required if paymentSource is set to MOTO.

    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.

    The device object and its attributes are not required if paymentSource is set to MOTO.

    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();

    The device object and its attributes are not required if paymentSource is set to MOTO.

    Format

    device.language

    String indicating the language of the browser.

    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;

    The device object and its attributes are not required if paymentSource is set to MOTO.

    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;

    The device object and its attributes are not required if paymentSource is set to MOTO.

    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;

    The device object and its attributes are not required if paymentSource is set to MOTO.

    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();

    The device object and its attributes are not required if paymentSource is set to MOTO.

    Format

    customer.reference

    Buyer ID on the merchant side.

    Format

    customer.email

    Buyer's e-mail address.

    Format

    customer.ipAddress

    Buyer's IP 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

    identityType

    Path: customer.billingDetails.identityType

    ID type.

    Possible values:

    Type Description
    DNI Documento Nacional de Identidad
    CC Cédula de ciudadania
    TI Tarjeta de Identidad
    CE Cédula de Extranjeria
    NI Número de Identificación Tributaria
    PS Pasaporte

    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.

    The device object and its attributes are not required if paymentSource is set to MOTO.

    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

    acquirerTransientData

    Allows to transmit information specific to certain acquirers.

    Utilisation avec Conecs

    Champ facultatif qui permet de transmettre le montant des produits éligibles payables par carte Titre-Restaurant CONECS.

    Si le champ n’est pas transmis, c'est la totalité du montant qui sera considérée comme éligible au paiement par Titre-Restaurant, y compris les frais éventuels de livraison inclus dans le montant de la commande.

    Exemple pour un montant éligible de 17.25€ :

    Exemple :

    {"CONECS":{"eligibleAmount":"1725"}}

    Restrict the accepted BIN codes

    To limit the accepted payment cards based on their BIN code, the expected format is:

    {"MULTI":{"bins": ["bin1","bin2","bin3"]}}

    NB: Support 6 digits BIN codes or 8 digits BIN codes.

    Example:
    BIN code at 6 digits: 4012 34XX XXXX XXXX;
    BIN code at 8 digits: 4000 1234 XXXX XXXX.

    Format

    contrib

    Name of the e-commerce solution used on the merchant website and its version number.

    Format

    ipnTargetUrl

    You can override the Instant Payment Notification (also called IPN) in the payment form in case you use one shop for various sales channels, payment types, languages, etc.

    Format

    fingerPrintId

    This field is used by merchants who implement the risk analyzer in their payment page. Allows you to send the session ID (or fingerPrint Id) to the payment platform to finalize the risk analysis.

    The supported analyzers are:

    • NOTO
    • Cybersource
    • MonitorPlus
    • ClearSale

    Can contain uppercase and lowercase characters, numbers or hyphens ([A-Z] [a-z], 0-9, _, -).

    Format

    metadata

    Custom values linked to the transaction, in JSON format.

    Example of a call

    For example, to pass a custom value, such as the Buyer's eye color, add the following to your query:

    {
        "metadata": {
            "eyesColor": "blue"
        }
    }

    This value will be returned in the newly created transaction object.

    You can also use the metadata " orderInfo1 ", " orderInfo2 " and " orderInfo3 " to send complementary information about the order.

    This data can be found later in the Extra tab of the transaction details via your Merchant Back Office.

    Format

    merchantPostUrlRefused

    Allows to define the URL to which the browser will be redirected after a failed 3D Secure authentication.

    Format

    merchantPostUrlSuccess

    Allows you to set the URL for browser redirection after a successful 3D Secure authentication.

    Format

    strongAuthentication

    strongAuthentication is used to indicate the Merchant's preference for strong buyer authentication.

    With 3DS2, it is no longer possible to disable 3DS. However, the merchant can request an exemption in his payment request (this is called "merchant preference").

    In this case, if the request is accepted by the issuer, the Buyer will not have to authenticate him/herself (no challenge) but the Merchant will assume the responsibility in case of chargeback (no liability shift to the issuer).

    In any case, the issuing bank itself determines whether interaction with the Buyer (challenge) is necessary.

    As part of PSD2 implementation, strong authentication is required when registering a card. This is the case when formAction is set to REGISTER_PAY but also ASK_REGISTER_PAY and CUSTOMER_WALLET if the buyer decides to register his payment method. The strongAuthentication field is ignored and the CHALLENGE_MANDATE value is applied automatically.

    Possible values

    The possible values are:

    Value 3DS1 description 3DS2 description
    ENABLED

    Enables strong authentication (if possible).

    Depreciated.This value will be interpreted as CHALLENGE_REQUESTED.

    DISABLED

    Disables (if possible) strong authentication. Requires the "3DS1 Selective" option..

    By using this value, you expose yourself to "Soft decline" refusals.

    Deactivation will not be taken into account if the payment method requires strong authentication. This is the case for MAESTRO cards.

    Allows to request authentication without interaction (frictionless). Requires the "Frictionless 3DS2" option.

    • Low value transaction

      For payments in euro, you can request an exemption from strong authentication, for transactions of less than €30, and within the limit of either 5 successive transactions or a cumulative amount of less than €100.

      If the amount is higher than €30, the value transmitted by the merchant is ignored and the choice of the preference is delegated to the card issuer (No Preference).

      For payments made in a currency other than euro, a frictionless request is sent to the issuer.

      If the request for frictionless is accepted, the transaction does not benefit from the liability shift in case of chargeback.

    If the shop does not have the "Frictionless 3DS2" option, the choice of preference is delegated to the card issuer (No Preference).

    CHALLENGE_REQUESTED

    Enables strong authentication (if possible).

    Allows you to request strong authentication for the transaction.

    CHALLENGE_MANDATE

    Enables strong authentication (if possible).

    Allows you to indicate that for regulatory reasons, strong authentication is required for the transaction.

    NO_PREFERENCE

    Enables strong authentication (if possible).

    Indicates to the DS that the merchant does not have a preference. If the issuer decides to perform frictionless authentication, the payment will be guaranteed.

    AUTO

    Enables strong authentication (if possible).

    The choice of preference is delegated to the card issuer (No Preference).

    Format

    paymentSource

    Path: transactionOptions.cardOptions.paymentSource

    Payment source.

    Format

    Possible values

    The possible values are:

    Value Description
    EC E-Commerce: the data of the means of payment are entered by the buyer. This value allows a strong authentication during the payment.
    MOTO MAIL OR TELEPHONE ORDER: entry by an operator.The payment information is sent by mail or e-mail. Requires a VAD contract.
    CC Call Center: payment made through a call center. Requires a VAD contract.
    OTHER Other sales channel.Returned output value for payments made via the Merchant Back Office, payments by file, recurring payments, proximity payments.
    Absent ou null The default value is "EC".

    mid

    Path: transactionOptions.cardOptions.mid

    Merchant ID number. If this field is populated, make sure you use the appropriate MID depending on the card scheme.

    Format

    manualValidation

    Path: transactionOptions.cardOptions.manualValidation

    Transaction validation mode.

    Format

    Possible values

    The possible values are:

    Value Description
    NO Automatic validation by the payment gateway.
    YES Manual validation by the Merchant.
    null Default configuration of the selected shop (configurable in the Merchant Back Office).

    captureDelay

    Path: transactionOptions.cardOptions.captureDelay

    Delay to be applied to the capture date.

    Description

    Indicates the delay (in days) before the capture.

    If this parameter is not passed, then the default value set in the Merchant Back Office will be used.

    It can be set in the Merchant Back Office by all authorized persons.

    If the capture delay is higher than 365 days in the payment request, it will be automatically reset to 365 days.

    Format

    firstInstallmentDelay

    Path: transactionOptions.cardOptions.firstInstallmentDelay

    Number of deferred months to be applied to the first installment of payment in installments. Field specific to acquirers in Latin America.

    Format

    installmentNumber

    Path: transactionOptions.cardOptions.installmentNumber

    Number of installments.

    Format

    retry

    Path: transactionOptions.cardOptions.retry

    Number of new attempts available in case the payment is rejected (3 by default).

    Format

    debitCreditSelector

    Path: transactionOptions.cardOptions.debitCreditSelector

    This field is specific to Brazil for multiplo card management.

    "Multiplo" cards are payment cards (Elo, Visa or MasterCard) that allow to pay using:

    • Either immediate debit: the amount is debited immediately, and the merchant is credited on D+1.
    • or in credit: the debit is deferred and the amount can be debited in one or more installments. The merchant is credited later with all or only part of the total amount.

    This field allows you to force the use of the card in debit or credit mode.

    Possible values

    values Description
    DEBIT Using the "debit" function of the card.
    CREDIT Using the "credit" function of the card.

    Format

    name

    Path: authenticationDetails.protocol.name

    Name of the protocol used by the cardholder authentication services.

    Possible values

    Value Description
    THREEDS 3D Secure protocol

    Format

    version

    Path: authenticationDetails.protocol.version

    Version of the protocol used by the cardholder authentication services.

    Possible values

    Value Description Compatible protocol
    1 To be filled in if the exact version is not known. In this case, the latest version supported in 3D Secure 1 by the payment platform will be considered All
    2 must be filled in if the exact version is not known. In this case, the latest version supported in 3D Secure 2 by the payment platform will be considered All
    1.0.2 Version 1.0.2 THREEDS
    2.1.0 Version 2.1.0 THREEDS
    2.2.0 Version 2.2.0 THREEDS

    Format

    directoryServer

    Path: authenticationDetails.protocol.directoryServer

    Name of the DS network where the authentication took place.

    Possible values

    PROTOCOL NAME DIRECTORYSERVER VALUE NETWORK NAME
    THREEDS AMEX American Express network (SafeKey)
    CB Réseau Carte Bancaire
    VISA Réseau Visa
    ELO Réseau Elo (Brésil)
    DINERS Réseau Diners
    DISCOVER Réseau Discover
    ELO Réseau Elo

    Format

    challengePreference

    Path: authenticationDetails.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.
    DATA_ONLY Disabled 3DS1 authentication. 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 shift The 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 field transactionCategory is not valued at PAYMENT.

    Format

    authenticationType

    Path: authenticationDetails.authenticationType

    Type of authentication that has been applied.

    Possible values

    Value Description
    FRICTIONLESS Authentication in Frictionless mode, i.e. transparent for the Buyer.
    CHALLENGE Authentication with a Challenge, the Buyer had to explicitly authenticate him/herself via the ACS.
    DATA_ONLY Authentication processed by the DS without client interaction

    Format

    status

    Path: authenticationDetails.status

    Authentication status, i.e. the positive/negative outcome of the authentication.

    Possible values

    Value Description
    ATTEMPT Proof of authentication attempt when authentication is not available.
    ENROLLED_UNAVAILABLE Unable to assess the enrollment status.
    FAILED Authentication error.
    NOT_ENROLLED Card not enrolled.
    SUCCESS Successful authentication.
    UNAVAILABLE The authentication could not be completed (technical error, etc.).
    DISABLED Disabled authentication. The exemption field becomes mandatory.

    Format

    commerceIndicator

    Path: authenticationDetails.commerceIndicator

    Commerce Indicator, or ECI (Electronic Commerce Indicator) for the 3DS protocol. Indicator returned by the ACS to report the results of cardholder's authentication attempt.

    In case of authentication without payment (e.g. in case of card registration) MasterCard can return the following 2 values:

    VALUE DESCRIPTION
    N0 Not authenticated
    N2 Authenticated

    Format

    authenticationValue

    Path: authenticationDetails.authenticationValue

    Final authentication value (depending on the DS this value can be called CAVV, AEVV or AAV). Character string encoded in base64 with a size of 28 characters.

    Format

    dsScore

    Path: authenticationDetails.dsScore

    Authentication score indicated by the DS.

    Format

    authValueAlgorithm

    Path: authenticationDetails.authValueAlgorithm

    Algorithm used to calculate the authenticationValue field. This field is mandatory in 3D Secure V2 CB as well as in 3D Secure V1 with an authentication value (non-zero CAVV).

    Format

    requestorName

    Path: authenticationDetails.requestorName

    RequestorName used during the initial authentication. Usually this field is the name of the merchant.

    Format

    dsTransID

    Path: authenticationDetails.dsTransID

    DS transaction ID. (Required in 3D Secure V2).

    Format

    acsTransID

    Path: authenticationDetails.acsTransID

    ACS Transaction ID. (Required in 3D Secure V2).

    Format

    xid

    Path: authenticationDetails.xid

    Unique transaction ID.(Required in 3D Secure V1).

    Format

    exemption

    Path: authenticationDetails.exemption

    Indicates the reason for the lack of strong authentication (Required in case of DISABLED status, or in case of FRICTIONLESS authentication).

    Possible values

    values Description
    LOW_VALUE Low value transaction (e.g.: amount less than 30€ in Europe)
    ACQUIRER_TRA Prior risk analysis carried out by the buyer
    ISSUER_TRA Prior risk analysis carried out by the issuer
    LOW_RISK_MERCHANT Merchant enrolled in the LOW RISK MERCHANT CB program
    OUT_OF_SCOPE Authentication not required as it is outside the RTS SCA scope
    DELEGATED_SCA Strong authentication delegated to a third party.
    FIXED_RECURRING_PAYMENT Recurring payment with a fixed amount and term
    TRUSTED_BENEFICIARY Trusted beneficiary
    AUTOMATIC_PAYMENT_MACHINES Payment terminal
    CORPORATE Secure payment procedure for companies
    OTHER_EXEMPTION Other use cases exempt from authentication
    TECHNICAL_ERROR Technical problem rendering authentication impossible

    Format

    challengeCancelationIndicator

    Path: authenticationDetails.challengeCancelationIndicator

    Challenge cancellation indicator received in the RReq. (Value returned by the DS in case of authentication cancellation).

    Format

    transactionStatusReason

    Path: authenticationDetails.transactionStatusReason

    Indicates the reason for the authentication failure. (Value returned by the DS in case of authentication failure).

    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 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.
    DATA_ONLY Disabled 3DS1 authentication. 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 shift The 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 field transactionCategory is not valued at PAYMENT.

    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

    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

    operationSessionId

    Unique identifier of the authentication, in UUID format.

    It is not defined upon the first call.

    The operationSessionId is returned as a result of a payment request that requires authentication of the bearer. It must be passed on to subsequent calls.

    Format

    companyType

    Path: subMerchantDetails.companyType

    Company type of the sub-merchant.Transmitted by the payment facilitator.

    Format

    legalNumber

    Path: subMerchantDetails.legalNumber

    Legal identifier of the sub-merchant.Transmitted by the payment facilitator.

    Format

    name

    Path: subMerchantDetails.name

    Business name of the sub-merchant.Transmitted by the payment facilitator.

    Format

    url

    Path: subMerchantDetails.url

    URL of the sub-merchant.Transmitted by the payment facilitator.

    Format

    phoneNumber

    Path: subMerchantDetails.phoneNumber

    Telephone number of the sub-merchant.Transmitted by the payment facilitator.

    Format

    address1

    Path: subMerchantDetails.address1

    Address of the sub-merchant.Transmitted by the payment facilitator.

    Format

    address2

    Path: subMerchantDetails.address2

    Addition of the sub-merchant's address. Transmitted by the payment facilitator.

    Format

    zip

    Path: subMerchantDetails.zip

    Zip code of the sub-merchant.Transmitted by the payment facilitator.

    Format

    city

    Path: subMerchantDetails.city

    City of the sub-merchant.Transmitted by the payment facilitator.

    Format

    country

    Path: subMerchantDetails.country

    Country code of the sub-merchant address (ISO 3166 alpha-2 standard). Transmitted by the payment facilitator.

    Format

    mcc

    Path: subMerchantDetails.mcc

    MCC code of the sub-merchant.Transmitted by the payment facilitator.

    Format

    mid

    Path: subMerchantDetails.mid

    Contract number (MID) of the sub-merchant.Transmitted by the payment facilitator.

    Format

    softDescriptor

    Path: subMerchantDetails.softDescriptor

    Label (Soft-descriptor) of the sub-merchant that appears on the buyer's bank statement. Transmitted by the payment facilitator.

    Format

    Response reference

    Several responses are possible, depending on the context:

    Response Context
    Payment Object containing the generated transaction. This object is directly returned during a single payment by token.
    AuthenticationResponseData Object returned if 3DS authentication is required.

    See response references for more information.