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 Merchant Back Office, in transaction details ( Shopping cart tab).

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.

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.

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

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 Merchant Back Office. The URL configured in the notification rule will be the one called.

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