The orderData/orderTag field, present in the service contract, must not be used.
The PaymentSession is a way of initializing a payment with all the necessary data (order informations, customer informations, payment method...) without having to proceed all the different stages yourself.
Having creating a session you will get an URL wich will provide a paymentform, so the customer will be able to complete the payment stages all by himself.
The API route to use is the following :
- Integration : POST https://paymentgateway.integration-cb4x.fr/v1/payment-sessions
- Production : POST https://paymentgateway.cb4x.fr/v1/payment-sessions
Headers of the request :
- Content-type : application/json
- authToken : the token retrieved via the call to the authentication service
Usefull Fields (see complete description in the swagger )
| Field | Description | Type | Mandatory ? |
|---|---|---|---|
| merchantId | Your merchant identifier | int32 | Yes |
| merchantSiteId | Your merchant site identifier | string | Yes |
| customer.customerRef | Reference of the customer | string | Yes |
| customer.firstName | First Name of the customer. Will be displayed in the field Cardholder if sent (see picture below) | string | No |
| customer.lastName | Last Name of the customer. Will be displayed in the field Cardholder if sent (see picture below) | string | No |
| orderData.amount | Amount of the order in cents Floa fees included (use the value of eligibilities.totalAmount got in the return of the eligibility call) | int64 | Yes |
| orderData.orderSummaryRef | Order reference, we recommend to send the same value as the value sent in presaleFolder.shoppingCarts.reference in the eligibility call | string30 | Yes |
| orderData.orderRef | Order reference, we recommend to send the same value as the value sent in presaleFolder.shoppingCarts.reference in the eligibility call | string30 | Yes |
| orderData.orderDate | Date of the order (is used to show the schedule of the order on the payment page) | date-time | Yes |
| orderData.scoringToken | Eligibility token retrieved from the eligibility call response in eligibilities.token. | string | Yes |
| orderData.freeText | You can send here what you what . This data will be sent in the post after payment. | string | No |
| orderData.orderRowsAmount | Amount of the order in cents, this value will be displayed on the line Items if sent (see picture below) | int64 | No |
| orderData.orderShippingAmount | Shipping amount in cents, this value will be displayed on the line Delivery if sent (see picture below) | int64 | No |
| orderData.orderDiscountAmount | Discount amount in cents, this value will be displayed on the line Voucher / promo code if sent (see picture below) | int64 | No |
| orderData.orderFeesAmount | Fees amount in cents, this value will be displayed on the line Management fee if sent (see picture below) | int64 | No |
| configuration.culture | See International page to see all the authorized values. Is used to choose the language of the payment page. | string | Yes |
| template | = Generic Always use this value | string | Yes |
| formType | = default if paymentPage integration = iframe if iFrame integration | string | Yes |
| merchantBackUrl | Link to the previous page. Will be the link behind BACK TO THE BASKET and Change payment method on the payment page (see picture below) | string | No |
| merchantNotifyUrl | Url where we will POST payment result, see Payment Notification page. | string | Yes |
| merchantReturnUrl | Url where we will redirect the customer after payment and POST payment result, see Payment Notification page. | string | Yes |
| paymentOptionRef | PaymentOptionRef of your site identifier | string | Yes |
Example of a payment page
Example of a json content
{
"merchantId": 38,
"merchantSiteId": "7017",
"customer": {
"customerRef": "00000001",
"firstName": "WilTest",
"lastName": "MazTest"
},
"orderData": {
"amount": 15000,
"orderSummaryRef": "387017001",
"orderRef": "387017001",
"orderDate": "2023-06-29T13:09:57.079Z",
"scoringToken": "e9baa39c-5b33-4fa2-85d7-455ebef4f2ca",
"freeText": "everythingYouWant",
"orderRowsAmount" : "110000",
"orderShippingAmount" : "4500",
"orderDiscountAmount" : "1000",
"orderFeesAmount" : "500"
},
"configuration": {
"culture": "fr-FR",
"template": "Generic",
"formType": "default",
"merchantBackUrl": "https://partner.com/merchantBackUrl",
"merchantNotifyUrl": "https://partner.com/merchantNotifyUrl",
"merchantReturnUrl": "https://partner.com/merchantReturnUrl",
"paymentOptionRef": "63"
}
}
Example of a response
{
"operationSucceeded": true,
"paymentSessionId": "59c51e43-a92e-4d1b-97a9-f41110820376",
"paymentSessionUrl": "https://payment.integration-cb4x.fr/Generic/CardPayment/Initialization?requestId=59c51e43-a92e-4d1b-97a9-f41110820376&hmacPay=0DA01CB9C9CA7AFC0539C04D2B35F41C113337AE",
"complementaryCode": "Undefined",
"responseMessage": ""
}
paymentSessionUrl is the URL where to redirect your customer. It will display the payment Page.
During your tests
If mandatory fields are missing in the payment session generation, you may receive a "returncode: 2" in return and your payment test is rejected.