Charge/CreatePaymentOrder web service

Le Web Service Charge/CreatePaymentOrder permet de créer des ordres de paiement via différents canaux de diffusion.

To see the payment result, implement the instant payment notification (also known as IPN).

1. In the REST API section (TEST or PRODUCTION), enter only the notification URL: Procedure.
2. Analyze the IPN: Procedure.

Consult the Web Services Payment Order integration guide.

Input 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

Type of payment order to be created. The default value is URL.

Format

Possible values

. The possible values are:

BCC ("Blind Carbon Copy" or "Invisible Carbon Copy"). List of additional recipients of the payment order. These addressees are not visible to the main recipient. Use the semicolon ";" as a separator between each address.

Format

Allows you to customize the e-mail body. If the parameter is left blank, the default template will be applied.

Format

Contents

To customize the body of the e-mail, you can use the variables below:

Example: Hello, this e-mail contains a payment link for %amount% , valid until %end_date%. To confirm the payment, click on the following link: %url%.

E-mail recipient.

Format

Allows you to customize the e-mail subject. This parameter is mandatory unless you specify a valid template name in the channelOptions.mailOptions.template parameter.

Format

Contents

To customize the e-mail subject, use the variables below:

Example: %reference% offer valid from %start_date% to %end_date% for an amount of %amount%.

Name of the template to be used for generating the e-mail. The template must exist in the Back Office for this to work.

Each e-mail template is associated with a language (or locale). To use a template, you must make sure that you transmit the right language in the locale parameter.

If the template is not found an error will be returned. If you have set a value in the subject and body parameters, the template will be ignored.

Format

SMS message.

Format

Phone number for sending the SMS.

Format

Phone number for sending WhatsApp messages.

Format

This field is normally filled in automatically by the platform. If the merchant has specific functional constraints, this field can exceptionally be overloaded with its own numerical reference, guaranteeing its uniqueness.

Format

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

Possible values

. The possible values are:

Format

Use of the data collection form. If set to true , the data collection form will be displayed before the payment form.

Format

Expiration date and time of the payment order, in ISO-8601 format.

Format

Regional (or local) parameter in cc_XX format, where:

• cc represents the language code (two lowercase characters according to ISO-639 (example "de" for German, "en" for English, "fr" for French).
• XX represents the country code (two uppercase characters according to ISO-3166 (e.g.: "DE" for Germany, "FR" for France, "GB" for the UK).

Allows you to set the language of the payment pages and the confirmation e-mail. If the parameter is not set, the language of the shop is used.

Format

Comment associated with the payment order. It is used, for example, to specify a reference about the payment order sender.

Format

Buyer's e-mail address to which the payment receipt is sent. This feature can only work if the notification rule "Confirmation e-mail sent to the buyer" is enabled in the Back Office.

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

allowDCFAmountUpdate is used to define whether the amount can be changed in the data collection form. This field can only be used if the dataCollectionForm field is set to true.

Format

Possible values

. The possible values are:

Format

Custom values linked to the transaction, in JSON format.

Example of a call

For example, to pass a custom value, add the following to your query:

{
    "metadata": {
        "MyValueKey": "1234"
    }
}

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

returnMode allows you to specify the data transmission method used when returning to the merchant site.

Possible values

. The possible values are:

Format

returnUrl allows to define the URL to which the buyer will be redirected by default after pressing the Return to shop button, if the errorUrl , refusedUrl , successUrl or cancelUrl URLs are not specified.

If the field is not transmitted, the Merchant Back Office configuration will be applied.

If no URL is defined in the Merchant Back Office or in the form, the Return to shop button will redirect the buyer to the merchant URL (URL field in the shop configuration).

Format

cancelUrl allows you to define the URL to which the buyer will be redirected if they press Cancel and return to the shop before proceeding to the payment.

Format

successUrl allows you to define the URL to which the buyer will be redirected in case of successful payment, after pressing the Return to shop button.

Format

refusedUrl allows you to define the URL to which the buyer will be redirected in case of refusal, after pressing the Return to shop button.

Format

errorUrl allows you to define the URL to which the buyer will be redirected in case of an internal processing error.

Format

postWalletUrl allows you to define the URL to which the buyer will be redirected when making a two-step payment using a wallet.

This URL is used for transmitting information related to the buyer's choice (e-mail, delivery address, payment method, etc.).

Based on these elements, the merchant can decide what action to take (adjust the shipping costs, register the payment method, etc.) before allowing the buyer to finalize their payment.

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

Allows to define a delay in seconds before an automatic redirection to the merchant website at the end of an accepted payment.

Its value is between 0 and 300 s.

After this time, the buyer will be redirected to the URL entered in the successUrl field. If this field is not filled in, the buyer will be redirected to the return URL filled in the returnUrl field or to the return URL filled in the bom. If the return URL is not defined, it will be redirected to the store URL.

Format

Allows to define a delay in seconds before an automatic redirection to the merchant website at the end of a declined payment.

Its value is between 0 and 300 s.

After this time, the buyer will be redirected to the URL entered in the errorUrl field. If this field is not filled in, the buyer will be redirected to the return URL filled in the returnUrl field or to the return URL filled in the bom. If the return URL is not defined, it will be redirected to the store URL.

Format

Buyer ID on the merchant side.

Format

Buyer's e-mail address.

• Email structure specifications: RFC-2822

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.

Format

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:

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

Token associated with a payment method.

Format

strongAuthentication is used to indicate the merchant preference during buyer authentication.

• Without cardholder interaction ( frictionless ).
• With cardholder interaction (strong authentication or challenge ).
• No merchant preference.

Strong authentication is required when registering a card. Use the formAction field with the following values:

• REGISTER_PAY : to make a payment while registering the payment method.
• ASK_REGISTER_PAY : to make a payment and request registration of the payment method.
• CUSTOMER_WALLET : to register the payment method.

In this case, the strongAuthentication field automatically takes the CHALLENGE_MANDATE value.

Table of exemptions (DISABLED value)

Format

List of payment methods to be offered to the buyer.

Example: ["VISA", "MASTERCARD"]

If this list contains only one payment method, the detail entry page for this payment method will directly appear. Otherwise the payment method selection page will be presented.

If this parameter is empty (recommended), the eligible payment methods (currencies, technical constraints, etc.) associated with the shop will be presented.

Format

Allows to transmit information specific to certain acquirers.

Use with Conecs

Optional field that allows to transmit the amount of items eligible for payment with the CONECS meal voucher card.

If the field is not transmitted, the whole amount will be considered eligible for payment by meal vouchers, including any delivery fees included in the order amount.

Example for an eligible amount of €17.25:

Example: .

{"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 : Supports 6-digit BIN codes or 8-digit BIN codes.

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

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 installments. Warning: This field is only applicable to Brazil

Format

First payment amount in N installments.

Format

Number of payment due dates in N installments.

Format

Interval (days) of payment in N installments.

Format

Maturity amount.

Format

Due date.

Format

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

Different rules may apply depending on the acquirer. This field is often used for specifying the type of Legal Number of the buyer.

Format

Legal number of sub-merchant according to field companyType . 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

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

Format

Payment Facilitator ID. Transmitted by the payment facilitator.

Format

Response reference

See the reference of each response for more information.