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).

Description
Transmitting the order number
Transmitting buyer details
Transmitting delivery details
Transmitting the contents of the shopping cart
Offering payment method registration
Using a registered payment method
Using a registered payment method without displaying the embedded form
Disabling v1 3D Secure
Transmitting merchant preferences
Increasing the chances of frictionless in 3DS2
Creating custom fields
Overriding the Instant Payment Notification

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:

  • visibles dans le Back Office Expert, dans le détail de la transaction (onglet Acheteur),
  • 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:

  • visibles dans le Back Office Expert, dans le détail de la transaction (onglet Livraison),
  • 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.

Ces données seront visibles dans le Back Office Expert, dans le détail de la transaction (onglet Panier).

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.
  • Pour que l’onglet Panier s’affiche correctement dans le Back Office Expert, vous devez transmettre au minimum le champ productAmount de chaque produit.

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 box.

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 populated. The Buyer will now have to enter the security code (CVV) to finalize the 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/she wishes to do so, provide the list of payment methods registered for the Buyer. To do this, he/she displays on his/her page the hidden pan and the expiry date that were returned upon payment method registration. The Buyer selects the payment method to be used 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, 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 your shop's configuration for payments by token, CVV entry or 3D Secure authentication may be required. In this case, the SILENT mode cannot be used.

Disabling v1 3D Secure

This feature requires a subscription for the Selective 3D Secure option.

The Merchant can indicate if he or she wishes to enable or disable strong authentication (e.g. 3D Secure or Safekey) during the call to the charge/createPayment web service.

To do this, use the strongAuthentication field.

Note:

Disabling 3D Secure will result in the loss of the liability shift. In the event of litigation or dispute initiated by the buyer, the eventual expenses could be charged to the Merchant.

{
  "strongAuthentication": "DISABLED"
}

Transmitting merchant preferences

With 3DS2, it will no longer be possible to disable 3DS. However, the merchant can request an exemption in his or her payment request (this is referred to as “merchant preferences”). To do this, use the strongAuthentication field.

Value 3DS1 description 3DS2 description
ENABLED

Activates (if possible) strong authentication.

Depreciated. This value will be interpreted as CHALLENGE_REQUESTED.

DISABLED

Disables strong authentication (if possible). Nécessite l'option "3DS1 Sélectif".

Deactivation will not be taken into account if the payment method requires strong authentication. This is the case of MAESTRO cards.

Allows to request authentication without interaction (frictionless). Requires the "Frictionless 3DS2" option.

  • For payments made in euro, if the amount is lower than €30, a request for frictionless is transmitted to the DS. If the request for frictionless is accepted by the issuer, the merchant loses the payment guarantee.

  • For payments made in euros, if the amount is greater than €30, the value transmitted by the merchant is ignored and the handling of cardholder authentication is delegated to the gateway.

  • For payments made in a currency other than euro, a frictionless request is sent to the DS.

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

Activates (if possible) strong authentication.

Allows you to request strong authentication for the transaction.

CHALLENGE_MANDATE

Activates (if possible) strong authentication.

Allows to indicate that, for regulatory reasons, strong authentication is required for the transaction.

NO_PREFERENCE

Activates (if possible) strong authentication.

Allows to indicate to the DS that the merchant does not have a preference. If the issuer decides to perform an authentication without interaction (frictionless), the payment will be guaranteed.

AUTO

Default value. Management of 3DS authentication delegated to the payment gateway (configuration of the domain, supplier, shop).

Default value. Management of 3DS authentication delegated to the payment gateway (configuration of the domain, supplier, shop).

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:

  • visibles dans le Back Office Expert, dans le détail de la transaction (onglet Extras),
  • 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"
  }
}

Overriding the Instant Payment Notification

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.

Cette fonctionnalité est incompatible avec l’exécution, depuis le Back Office Expert, de la requête envoyée à l’URL de notification instantanée.

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",
}