PCI/Charge/CreatePayment

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:

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

Example: 30050 for EUR 300.50.

Format

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

Eg: "EUR" for the euro.

Format

Possible values

The possible values are:

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

Format

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

Format

Possible values

The possible values are:

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.

Type of payment method.

Possible values

Format

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

Format

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

Format

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

Format

Card security code.

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

Format

Card brand.

Format

Cardholder's first and last names.

Format

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

Format

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

ID type.

Possible values:

Format

Number of installments.

Format

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

Format

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

Possible values:

Format

Token associated with a payment method.

Only tokens associated with a credit card are supported.

Format

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

Example: 30050 for EUR 300.50.

Format

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

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

Format

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

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

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

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

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

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

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

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

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

Buyer ID on the merchant side.

Format

Buyer's e-mail address.

Format

Buyer's IP address.

Format

Billing address.

Warning: the characters > and < are not authorized.

Format

Second line of the billing address.

Warning: the characters > and < are not authorized.

Format

Buyer type.

Format

Possible values

Buyer's cell phone number.

Accepts all formats:

Examples:

• 0623456789
• +33623456789
• 0033623456789
• (+34) 824 65 43 21
• 87 77 12 34

Format

City of the billing address.

Format

Buyer's country (in uppercase, in accordance with the ISO 3166-1 alpha-2 country codes).

Format

Possible values

Examples of possible values:

District of the billing address.

Format

Buyer's first name.

Format

National identifier. Allows to identify each citizen within a country.

Format

ID type.

Possible values:

Format

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:

Buyer's last name.

Format

Legal name.

Format

Buyer's phone number.

Accepts all formats:

Examples:

• 0123456789
• +33123456789
• 0033123456789
• (00.571) 638.14.00
• 40 41 42 42

Format

Region (state) of the billing address. It is recommended, but not mandatory, to pass the value in ISO-3166-2.

Format

Street number of the billing address.

Accepted characters:

• Alphabetical characters (from "A" to "Z" and from "a" to "z")
• Space

Format

Buyer's title.

Examples:

• Mr
• Ms.
• Mrs

Format

Zip code of the billing address.

Format

Shipping address.

Warning: the characters > and < are not authorized.

Format

Second line of the shipping address.

Warning: the characters > and < are not authorized.

Format

Buyer type.

Format

Possible values

Shipping city.

Format

Shipping country (in uppercase, in accordance with the ISO 3166-1 alpha-2 country codes).

Format

Possible values

Examples of possible values:

Name of the delivery company.

Format

District of the billing address.

Format

First name of the recipient.

Format

National identifier. Allows to identify each citizen within a country.

Format

Buyer's last name.

Format

Legal name in case of shipping to a company.

Format

Buyer's phone number.

Accepts all formats:

Examples:

• 0123456789
• +33123456789
• 0033123456789
• (00.571) 638.14.00
• 40 41 42 42

Format

Shipping mode.

Format

Possible values

Shipping delay.

Format

Possible values

Examples of possible values:

Region of the billing address.

Format

Street number of the delivery address.

Accepted characters:

• Alphabetical characters (from "A" to "Z" and from "a" to "z")
• Space

Format

Zip code of the billing address.

Format

Insurance amount for the entire order, expressed in the smallest monetary unit (cent for euro).

Example: 30050 for EUR 300.50.

Format

Amount of delivery fees for the entire order, expressed in its smallest monetary unit (cent for euro).

Example: 30050 for EUR 300.50.

Format

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

Example: 30050 for EUR 300.50.

Format

cardItemInfo is a list that contains Customer/ShoppingCartItemInfo objects.

It allows you to describe each item in the cart.

Format

Amount of the product expressed in the smallest currency unit (cent for euro).

Example: 30050 for EUR 300.50.

Format

Product name.

Format

Product quantity.

Format

Product reference.

Format

Product type.

Possible values

Format

Product type.

Tax fee amount (expressed in the smallest currency unit).

Possible values

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

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

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

Format

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

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

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

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

Format

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

Format

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:

Format

Payment source.

Format

Possible values

The possible values are:

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

Format

Transaction validation mode.

Format

Possible values

The possible values are:

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

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

Format

Number of installments.

Format

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

Format

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

Format

Name of the protocol used by the cardholder authentication services.

Possible values

Format

Version of the protocol used by the cardholder authentication services.

Possible values

Format

Name of the DS network where the authentication took place.

Possible values

Format

Indicates whether or not the Merchant has requested a challenge.

Possible values

Format

Type of authentication that has been applied.

Possible values

Format

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

Possible values

Format

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:

Format

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

Authentication score indicated by the DS.

Format

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 used during the initial authentication. Usually this field is the name of the merchant.

Format

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

Format

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

Format

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

Format

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

Possible values

Format

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

Format

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

Format

Instruction name.

Possible values

Format

Result as a JWT string, or a plain text error code in case of an error ( timeout for example).

Format

Indicates whether or not the Merchant has requested a challenge.

Possible values

Format

Name of the protocol used by the cardholder authentication services.

Possible values

Format

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

Format

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 of the protocol used by the cardholder authentication services.

Currently supported versions

Format

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

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

Format

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

Format

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

Format

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

Format

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

Format

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

Format

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

Format

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

Format

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

Format

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

Format

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

Format

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

Format

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:

See response references for more information.