Charge/CreatePayment Web Service
The Charge/CreatePayment operation is a REST API Web Service.
It allows to make several operations:
Creating a transaction using a new card
You can create transactions using a card, together with the embedded form.
In this case, the Charge/CreatePayment REST Web Service will return a formToken that you should then use with our JavaScript form.
For more information, go to Getting started: Single payment .
To see the reference documentation of the response containing the formToken, go to: Charge/PaymentForm .
Once the payment has been made, the newly created transaction will be included in the Payment object, documented here .
Creating a transaction using a token
You can also create a transaction using the previously recorded payment method (payment token).
For more information, go to: Payment by token .
Issue a SEPA direct debit request
You can trigger the generation of a SEPA Direct Debit request by using the Charge/CreatePayment Web Service in SILENT mode.
For more information, go to: Payment by token .
To see the response reference documentation, go to: Payment .
If you are PCI-DSS certified
If you are PCI-DSS certified, you can pass sensitive information (such as card number) directly to the Web Service.
From a contractual point of view:
For more information, reach out to your sales contact to make sure you are eligible for this option.
From a technical point of view
Go to our page dedicated to the use of the Charge/CreatePayment REST Web Service in PCI-DSS mode .
Request parameters
The 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
contrib
Name of the e-commerce solution used on the merchant website and its version number.
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 |
| Canadian dollar (124) | CAD | 2 |
| Danish crown (208) | DKK | 2 |
| Japanese yen (392) | JPY | 0 |
| Norwegian crown (578) | NOK | 2 |
| Swedish krona (752) | SEK | 2 |
| Swiss franc (756) | CHF | 2 |
| Pound Sterling (826) | GBP | 2 |
| US dollar (840) | USD | 2 |
| Euro (978) | EUR | 2 |
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
orderId
Order reference defined by the Merchant. Does not support UTF-8 characters.
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
Format
fingerPrintId
Disable the requested authentication Allows the session ID (or fingerPrint Id) to be transmitted to the payment gateway for completing 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
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 | Creating a payment method token at the same time as the transaction. Does not allow to create a token associated with an IBAN. |
| ASK_REGISTER_PAY | Adds a checkbox to the form for creating a token. Does not allow to create a token associated with an IBAN. |
| SILENT | Transaction initiated by the merchant without the presence of the buyer. Makes a payment by token without the use of an embedded form. |
| CUSTOMER_WALLET | Adds a checkbox to the form for associating the card with the wallet The customer.reference field is required for this use case See the integration guide for more information. |
| 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 .
ASK_REGISTER_PAY:
The Web Service will return a formToken .
This parameter allows you to add a checkbox to the payment form, asking the buyer if they want to record their card.
| buyer action | DESCRIPTION |
|---|---|
| The box is ticked | Records a card token (e.g. formAction=REGISTER_PAY). |
| The box is not checked | The token is not created (such as formAction=PAYMENT). Default behavior. |
For more information, go to the article dedicated to Creating and using tokens .
CUSTOMER_WALLET:
The Web Service will return a formToken .
This parameter allows to add a checkbox in the payment form, asking the buyer if they want to register their card in their wallet. Requires the customer.reference buyer reference.
| buyer action | DESCRIPTION |
|---|---|
| The box is ticked | Adds a card to the wallet. |
| The box is not checked | Default behavior. the card is not added to the wallet. |
SILENT: reserved for transactions initiated by the merchant without the presence of the buyer and in particular for recurring payments when recurrence is managed by the merchant.
In the PSD2 application area, cardholder authentication is mandatory when the cardholder is present. The SILENT mode is therefore reserved when the cardholder is absent or for merchants outside the PSD2 area.
In the PSD2 application area, the strongAuthentication field is ignored and no cardholder authentication is performed.
The Web Service will directly return a transaction rather than a formToken during a payment by token. The transaction is therefore carried out between servers.
paymentMethodToken
Token associated with a payment method.
Only tokens associated with a credit card are supported.
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 or her 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.
Under PSD2, strong authentication is required when registering a card. This is the case when formAction is set to REGISTER_PAY as well as ASK_REGISTER_PAY and CUSTOMER_WALLET if the buyer decides to register their payment method. The strongAuthentication field is ignored and the CHALLENGE_MANDATE value is automatically applied.
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 strong authentication (if possible). 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 of MAESTRO cards. | Allows to request an authentication without interaction (frictionless). Requires the "Frictionless 3DS2" option.
If the store does not have the "Frictionless 3DS2" option, the value transmitted by the merchant is ignored and the handling of the cardholder authentication is delegated to the gateway. |
| 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). | Allows you to inform 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
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"}}Format
customer.reference
Buyer ID on the merchant side.
Required if formAction is set to CUSTOMER_WALLET .
In this case, the buyer's reference is used as the wallet identifier.
Format
customer.email
Buyer's e-mail address.
If you want to create a payment method token (by setting formAction to REGISTER_PAY , ASK_REGISTER_PAY or CUSTOMER_WALLET ) the e-mail address is not required. However, the buyer will have to specify it in the form.
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.
paymentSource
Path: transactionOptions.cardOptions.paymentSource
Payment source.
Format
Possible values
The possible values are:
| Value | DESCRIPTION |
|---|---|
| EC | E-commerce: the payment method details are entered by the Buyer. This value allows to have strong authentication during a 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 via a call center. Requires a VAD type contract. |
| OTHER | Other sales channel. Returned output value for payments made via the Back-Office, payments by file, recurring payments, proximity payments, refunds via the Shopify CMS. |
| 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 |
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
It can be set in the
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 credit: the debit is deferred and the amount can be debited in one or more installments. The merchant is later credited with the entirety or a portion 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
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 be applied (21 for 21%)
Format
overridePaymentCinematic
Allows you to change the capture mode. Specific to buyers in Latin America. 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
formTokenVersion
formTokenVersion defines the version of the formToken returned by the Web Service.
This parameter is used for mobile SDK. It allows to make sure that the version of the returned formToken is still in line with the mobile application deployed on the buyer's phone.
The default value is 2.
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
Address line 2 of the sub-merchant. 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's 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
Title (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. |
| Charge/PaymentForm | Object containing a hash that should be used with the embedded form to create a new transaction. |
See the reference of each response for more information.