• France
Search
Categories
Tags
English
French
English
Implementation
Embedded form (cards)
REST payment API
Hosted payment
Push mail
File exchange
Mobile payment
Logos
Plugins
Back office
Guides
Helpers
FAQ
Support

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
Send the sub-merchant data
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:

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

Note The subMerchantDetails.name field becomes mandatory whenever at least one submerchant field is present in the payment request.

Field name Description Format
subMerchantDetails.address1 Address of the sub-merchant.Transmitted by the payment facilitator. ans..255
subMerchantDetails.address2 Addition of the sub-merchant's address. Transmitted by the payment facilitator. ans..255
subMerchantDetails.city City of the sub-merchant.Transmitted by the payment facilitator. an..128
subMerchantDetails.companyType Company type of the sub-merchant.Transmitted by the payment facilitator. ans..60
subMerchantDetails.country Country code of the sub-merchant address (ISO 3166 alpha-2 standard). Transmitted by the payment facilitator. a2
subMerchantDetails.legalNumber Legal identifier of the sub-merchant.Transmitted by the payment facilitator. ans..24
subMerchantDetails.mcc MCC code of the sub-merchant.Transmitted by the payment facilitator. n4
subMerchantDetails.mid Contract number (MID) of the sub-merchant.Transmitted by the payment facilitator. n..64
subMerchantDetails.name Business name of the sub-merchant.Transmitted by the payment facilitator. an..255
subMerchantDetails.phoneNumber Telephone number of the sub-merchant.Transmitted by the payment facilitator. an..32
subMerchantDetails.softDescriptor Label (Soft descriptor) of the sub-merchant that appears on the buyer's bank statement. Transmitted by the payment facilitator. ans..255
subMerchantDetails.url URL of the sub-merchant.Transmitted by the payment facilitator. ans..128
subMerchantDetails.zip Zip code of the sub-merchant.Transmitted by the payment facilitator. an..64

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.

Disabling v1 3D Secure

This feature will no longer be available with the implementation of 3DS2.

As of September 2020, issuers can decline the transaction if 3D Secure v1 authentication has not been performed. This behavior is called "Soft Decline". To reduce the number of declined payments, the payment platform automatically performs a new payment attempt with 3D Secure authentication.

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

If the payment method necessarily requires strong authentication, as is the case with MAESTRO cards, the parameter will be ignored.

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 called "merchant preference").

To do this, use the strongAuthentication field.

Value 3DS1 description 3DS2 description
ENABLED

Enables strong authentication (if possible).

Depreciated.This value will be interpreted as CHALLENGE_REQUESTED.

DISABLED

Disables (if possible) strong authentication. Requires the "3DS1 Selective" option..

Deactivation will not be taken into account if the payment method requires strong authentication. This is the case for 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 shop does not have the "Frictionless 3DS2" option, the choice of preference is delegated to the card issuer (No Preference).

CHALLENGE_REQUESTED

Enables strong authentication (if possible).

Allows you to request strong authentication for the transaction.

CHALLENGE_MANDATE

Enables strong authentication (if possible).

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

NO_PREFERENCE

Enables strong authentication (if possible).

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. Enable (if possible) strong authentication.

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.

  • The use of these fields is optional. In all cases, it is the issuing bank that decides if a strong authentication should be performed.
  • These fields and their values will only be taken into account after 3DS2 has been enabled for your MID.
  • This list is non-exhaustive and will be completed shortly.

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

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.

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",
}
© 2023 | All rights reserved to Systempay | legal
2.16.0-doc-1.8