Use cases
Here is a non-exhaustive list of use cases that are defined when initiating the payment (when calling the Charge/createPayment web service).
Transmitting the order number
To transmit the order number, use the orderId field:
{ "orderId" : "CX-1254" }
Transmitting buyer details
The Merchant may transmit the Buyer's billing address and contact information (e-mail address, title, phone number etc.).
These details will be:
- Visible in the
Merchant Back Office , in the transaction details ( Buyer tab), - Returned in the IPN, without modification.
To do this, use the customer field:
Example
{ "customer": { "reference":"C2383333540", "email" : " <sample@example.net>", "billingDetails" : { "category" : "PRIVATE", "title" : "M", "firstName" : "Laurent", "lastName" : "DURANT", "streetNumber" : "109", "address" : "rue de l'innovation", "zipCode" : "31670", "city" : "LABEGE", "country" : "FR", "phoneNumber" : "0123456789", "cellPhoneNumber" :"0623456789" } } }
Transmitting delivery details
The Merchant can transmit the Buyer's delivery details (address, title, phone number etc.).
These details will be:
- Visible in the
Merchant Back Office , in the transaction details ( Buyer tab), - Returned in the IPN, without modification.
Example for a delivery of "In-store pickup" type.
The delivery address is the same as the shop address.
The billing address is different from the delivery address.
The name of the delivery recipient is the same one as in the billing address.
{ "customer": { "shippingDetails": { "shippingMethod": "RECLAIM_IN_SHOP", "shippingSpeed": "STANDARD", "streetNumber": "230", "address": "avenue des Champs Elysées", "zipCode": "59170", "city": "CROIX", "country": "FR", "firstName": "Marie-Charlotte", "lastName": "GRIMALDI", "phoneNumber": "0328386789" } } }
Example for a "Pickup point" type delivery
The delivery address is the same as the pickup point address.
The name of the pickup point is transmitted in the second line of the delivery address.
The address of the pickup point is transmitted in the first line of the delivery address.
The recipient's name is the one mentioned in the billing address.
The billing address is different from the delivery address.
{ "customer": { "shippingDetails": { "shippingMethod": "RELAY_POINT", "shippingSpeed": "STANDARD", "streetNumber": "100", "address": "avenue du parc Barbieux", "address2": "Pressing du Parc", "zipCode": "59170", "city": "CROIX", "country": "FR", "firstName": "Martine", "lastName": "DURAND", "phoneNumber": "0328386789", "deliveryCompanyName":"Chronospost" } } }
Transmitting the contents of the shopping cart
When creating a payment, the Merchant can transmit the contents of the Buyer's cart.
These details will be visible in the
For this, use the cartItemInfo (json object array) field when calling the Charge/CreatePayment web service.
Example for defining 2 items in the shopping cart
{ "customer": { "shoppingCart": { "cartItemInfo": [ { "productRef": "myRef1", "productAmount": "1200", "productLabel": "myLabel1", "productQty" : "1" }, { "productRef": "myRef2", "productAmount": "2400", "productLabel": "myLabel2", "productQty" : "1" } ] } } }
Notes:
- The cartItemInfo field is always returned to empty in the response.
- In order for the Shopping cart tab to be displayed correctly in the
Merchant Back Office , you must pass at least the productAmount field of each product.
Send the sub-merchant data
The Payment Facilitator can transmit the data of the sub-merchant involved in the transaction.
This data will be :
- Visible in the
Merchant Back Office , in the transaction details ( Buyer tab), - Returned in the IPN, without modification.
The table describes the common fields available with sub-merchant information.
Field name | FORMAT | Description |
---|---|---|
subMerchantDetails.address1 | ans..255 | Address of the sub-merchant.Transmitted by the payment facilitator. |
subMerchantDetails.address2 | ans..255 | Addition of the sub-merchant's address. Transmitted by the payment facilitator. |
subMerchantDetails.city | an..128 | City of the sub-merchant.Transmitted by the payment facilitator. |
subMerchantDetails.companyType | ans..60 | Company type of the sub-merchant.Transmitted by the payment facilitator. |
subMerchantDetails.country | a2 | Country code of the sub-merchant address (ISO 3166 alpha-2 standard). Transmitted by the payment facilitator. |
subMerchantDetails.facilitatorId | ans..128 | Payment Facilitator ID. Transmitted by the payment facilitator. |
subMerchantDetails.legalNumber | ans..24 | Legal identifier of the sub-merchant.Transmitted by the payment facilitator. |
subMerchantDetails.mcc | n4 | MCC code of the sub-merchant.Transmitted by the payment facilitator. |
subMerchantDetails.mid | n..64 | Contract number (MID) of the sub-merchant. Transmitted by the payment facilitator. |
subMerchantDetails.name | ans..255 | Business name of the sub-merchant.Transmitted by the payment facilitator. |
subMerchantDetails.phoneNumber | an..32 | Telephone number of the sub-merchant.Transmitted by the payment facilitator. |
subMerchantDetails.softDescriptor | ans..255 | Label (Soft descriptor) of the sub-merchant that appears on the buyer's bank statement. Transmitted by the payment facilitator. |
subMerchantDetails.state | ans..128 | Region of the sub-merchant's address. Transmitted by the payment facilitator. |
subMerchantDetails.url | ans..128 | URL of the sub-merchant.Transmitted by the payment facilitator. |
subMerchantDetails.zip | an..64 | Zip code of the sub-merchant.Transmitted by the payment facilitator. |
Offering payment method registration.
The Merchant may offer the Buyer to facilitate their purchases by requesting to register banking details via the payment gateway.
With this operation, the payment gateway allocates a unique token to the payment method and returns it to the Merchant via the paymentMethodToken field.
Thus, the Buyer will no longer have to enter their payment method details during subsequent purchases.
This solution brings an additional level of security to payments since only the token that can only be used by the payment gateway is transmitted.
To offer the Buyer to register their payment method during the payment, use the formAction field with the ASK_REGISTER_PAY value
{ "formAction" : "ASK_REGISTER_PAY", "customer": { "email": " <sample@example.net>" } }
Note:
The e-mail field becomes mandatory when recording the payment method.
When the form is displayed, a checkbox will appear.
By default, this box is unchecked.
If the Buyer accepts to record their payment method, they must tick the box.
If the payment is refused, the payment method will not be recorded.
Force payment method registration
If the Merchant has notified the buyer earlier in the purchase process, they can "force" payment method registration without displaying an additional checkbox.
For this, use the formAction field with the REGISTER_PAY value:
{ "formAction" : "REGISTER_PAY", "customer": { "email": " <sample@example.net>" } }
Using a registered payment method
The Merchant can transmit the token to be debited when initiating the payment.
When the form is displayed, the kr-pan and kr-expiry fields will be automatically filled in. The buyer will only have to enter their security code (CVV) to finalize their purchase.
To do this, simply transmit the token to be debited in the paymentMethodToken field and set the formAction field to PAYMENT.
Since this is the default value, the formAction field is no longer needed.
{ "formAction" : "PAYMENT", "paymentMethodToken":"d3d9cc0d24a4400e9d123e9e1b8f1793", }
Using a registered payment method without displaying the embedded form
When the buyer wishes to make a new purchase, the merchant can, if he wishes, offer the list of payment methods registered for this customer. To do so, it displays on its page the obfuscated pan and validity date that were returned to it when the payment method(s) were registered. The buyer selects the payment method to use and the merchant initializes the payment with the associated token.
In order not to display the embedded form, all you need to do is use the formAction parameter and set it to SILENT :
{ "formAction" : "SILENT", "paymentMethodToken":"d3d9cc0d24a4400e9d123e9e1b8f1793", }
Note:
- This use case does not use the JavaScript client, but only a server-to-server call. There is no redirection to the return url specified in kr-post-url-success.
- The answer does not contain a formToken but directly a Transaction object.
- Depending on the configuration of your store regarding alias payments, it is possible that CVV entry or 3D Secure authentication is required. In this case, the SILENT mode may not be suitable.
Transmitting merchant preferences
With 3DS2, it is no longer possible to disable 3DS. The merchant must request an exemption in his payment request (this is called "merchant preference").
To do this, use the strongAuthentication field.
VALUE | 3DS2 description |
---|---|
ENABLED | Depreciated.This value will be interpreted as CHALLENGE_REQUESTED. |
DISABLED | Allows to request authentication without interaction (frictionless). Requires the "Frictionless 3DS2" option.
If the shop does not have the "Frictionless 3DS2" option, the choice of preference is delegated to the card issuer (No Preference). |
CHALLENGE_REQUESTED | Allows you to request strong authentication for the transaction. |
CHALLENGE_MANDATE | Allows you to indicate that for regulatory reasons, strong authentication is required for the transaction. |
NO_PREFERENCE | 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 | Default value. The choice of the preference is delegated to the card issuer ( No Preference). |
Increasing the chances of frictionless in 3DS2
When all the actors are operational, it will be possible to transmit additional data to increase the chances of frictionless payment.
List of fields to be transmitted
PARAMETER | Description |
---|---|
customer.email | Buyer's e-mail address. |
customer.billingDetails.identityCode | National identifier. Allows to identify each citizen within a country with a unique code. CPF or CNPJ in Brazil. |
customer.billingDetails.streetNumber | Street number of the billing address |
customer.billingDetails.address | Postal address |
customer.billingDetails.address2 | Address line 2 |
customer.billingDetails.zipCode | Zip code |
customer.billingDetails.city | City |
customer.billingDetails.state | State/Region |
customer.billingDetails.country | Country code according to the ISO 3166 alpha-2 standard |
customer.billingDetails.phoneNumber | Phone number |
customer.billingDetails.cellPhoneNumber | Cell phone number |
customer.shippingDetails.address | Postal address |
customer.shippingDetails.address2 | Address line 2 |
customer.shippingDetails.zipCode | Zip code |
customer.shippingDetails.city | City |
customer.shippingDetails.state | State/Region |
customer.shippingDetails.country | Country code according to ISO 3166 |
customer.shippingDetails.shippingMethod | Mode of delivery. New values specific to 3DS2 will be available soon |
customer.shippingDetails.shippingSpeed | Delivery time. New values specific to 3DS2 will be available soon |
Transmitting custom data
When creating a payment, the Merchant can transmit specific information to the payment gateway in order to meet their business needs.
For example: a file number, contract number, etc.
These details will be:
- Visible in the
Merchant Back Office , in the transaction details ( Buyer tab), - Visible in the payment confirmation e-mail sent to the Merchant.
- Returned in the notification URL, without change.
For this, use the metadata (in JSON format) fields when calling the Charge/CreatePayment web service:
Example of transmitting a piece of data entitled "contract" and its value:
{ "metadata": { "contract": "1245KL-78/ZE" } }
Override the instant notification URL (not recommended)
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.
This feature is incompatible with the execution of the request sent to the IPN URL via the
The URL configured in the notification rule is the one that will be called (see the "Setting up notifications" chapter).
Use the ipnTargetUrl field when initiating the payment to override the URL of the page to notify.
If the value in the ipnTargetUrl field is incorrect, the form will not be rejected.
{ "ipnTargetUrl" : "<https://my.site/my-ipn>", }