Charge/CreateToken Web Service
The Charge/CreateToken REST Web Service allows you to create an alias without payment.
Only bank cards are supported . This method does not allow you to create an alias from an IBAN.
Check out the integration guide Creating an alias without payment .
Input parameters
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 |
| Swiss franc (756) | CHF | 2 |
| Danish crown (208) | DKK | 2 |
| Euro (978) | EUR | 2 |
| Pound Sterling (826) | GBP | 2 |
| Japanese yen (392) | JPY | 0 |
| Norwegian crown (578) | NOK | 2 |
| Swedish krona (752) | SEK | 2 |
| US dollar (840) | USD | 2 |
formAction
formAction allows you to define the type of behavior desired when creating the token.
Format
Possible values
. The possible values are:
| value | Description |
|---|---|
| REGISTER | Creation of an alias (token) for the payment method. Does not allow you to create an alias associated with an IBAN. |
| CUSTOMER_WALLET | Adds the list of aliases associated with the buyer reference in the form. The customer.reference field is mandatory for this use case. |
| null | If the value is null or undefined, REGISTER applies. |
REGISTER:
The Web Service will return a formToken.
This is the default behavior. Calling Charge/CreateToken creates an alias.
The Web Service will return a formToken.
This parameter allows you to add the alias list to the card registration form. Requires the buyer reference customer.reference .
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, 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
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
strongAuthentication
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.
When registering a card, strong authentication is required, regardless of merchant preference.
| Use cases | Possible values |
|---|---|
| CHALLENGE : With cardholder interaction |
|
| |
| |
“Frictionless 3DS2” option mandatory |
If you do not have the “Frictionless 3DS” option, the choice of preference is delegated to the card issuer (No Preference). If the request for frictionless is accepted, the transaction does not benefit from the liability shift in case of a dispute by the cardholder. |
| No merchant preference |
|
|
Table of exemptions (DISABLED value)
| exemption | Description |
|---|---|
| Low value transaction | For payments in EUR, you can requestan exemptionTo strong authentication:
|
| LRM (Low Risk Merchant) |
CB's LRM (Low Risk Merchant) program aims to meet the expectations of merchants with very low risk and high volume (120,000 CB transactions / year). You can request an exemption from strong authentication: |
Format
customer.reference
Buyer ID on the merchant side.
Format
customer.email
Buyer's e-mail address.
- Email structure specifications: RFC-2822
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.
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
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
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
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 |
| Absent ou null | The default value is "EC". |
retry
Path: transactionOptions.cardOptions.retry
Number of new attempts available in case the payment is rejected (1 by default).
Format
companyType
Path: subMerchantDetails.companyType
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
legalNumber
Path: subMerchantDetails.legalNumber
Legal number of sub-merchant according to field companyType . 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
state
Path: subMerchantDetails.state
Region of the sub-merchant's address. Transmitted by the payment facilitator.
Format
facilitatorId
Path: subMerchantDetails.facilitatorId
Payment Facilitator ID. Transmitted by the payment facilitator.
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 4.
Format
Response reference
| Response | Context |
|---|---|
| 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.