Client Session

Definition

A Client Session is a resource used by merchants to initialize a payment process.
It is required before any other payment action and carries all necessary information to perform a transaction using the Payment API V2.

When a customer arrives at the merchant's payment page, the backend must issue a client-session, ensuring that the checkout is properly configured.

danger

The creation of a client session is mandatory before any other payment action.

---

Client Session Data

A Client Session contains essential details for payment processing, including:

• Order details
• Payment method eligibility
• Authorization status
• Customer and transaction information

Example: Client Session Request

Client Session Request Data example

{
  "entity_id": "{{entity_id}}",
  "amount": 11500,
  "currency": "EUR",
  "shopper_redirection_url": "https://www.example.com",
  "customer": {
    "reference": "2090000000000",
    "type": "PERSON",
    "email": "[email protected]",
    "gender": "FEMALE",
    "first_name": "Emily",
    "middle_name": "Rose",
    "last_name": "PARKER",
    "birth_date": "1995-08-25",
    "ip_address": "203.0.113.195",
    "locale": "fr-FR",
    "account": {
      "creation_date_time": "2017-06-15T15:30:00+02:00",
      "update_date_time": "2023-02-20T20:54:00+01:00",
      "password_update_date_time": "2023-02-20T20:54:00+01:00",
      "purchase_count_last_day": 0,
      "purchase_count_last_six_months": 3,
      "purchase_count_last_year": 8,
      "authentication_method": "MERCHANT_CREDENTIALS",
      "authentication_date_time": "2023-10-30T15:33:00+02:00",
      "age_indicator": "MORE_60_DAYS",
      "change_indicator": "MORE_60_DAYS",
      "password_change_indicator": "MORE_60_DAYS"
    }
  },
  "order": {
    "reference": "123456789",
    "net_amount": 12000,
    "discount_amount": 500,
    "tax_amount": 2000,
    "billing_address": {
      "gender": "FEMALE",
      "first_name": "Emily",
      "middle_name": "Rose",
      "last_name": "PARKER",
      "address_lines": [
        "NextNow",
        "67 Rue de Luxembourg"
      ],
      "city": "Lille",
      "postal_code": "59777",
      "country_code": "FR",
      "province_code": "FR-HDF",
      "phone_number": "+33111111111",
      "mobile_phone_number": "+33222222222",
      "work_phone_number": "+33444444444"
    },
    "shipments": [
      {
        "net_amount": 12000,
        "delivery_type": "EXTERNAL_PICKUP",
        "delivery_quickness": "REGULAR",
        "delivery_method_reference": "#1123-pickup",
        "estimated_delivery_date_time": "2023-10-30T15:40:00+02:00",
        "shipping_address": {
          "gender": "FEMALE",
          "first_name": "Rodriguez",
          "middle_name": "Eios",
          "last_name": "DESANTONS",
          "address_lines": [
            "Av. de la roja 1676"
          ],
          "city": "Porto",
          "postal_code": "22000",
          "country_code": "PT",
          "province_code": "PT-13",
          "phone_number": "+33555555555",
          "mobile_phone_number": "+33666666666",
          "work_phone_number": "+33777777777",
          "delivery_point_name": "home"
        },
        "item_lines": [
          {
            "type": "PHYSICAL",
            "sku_reference": "2600218",
            "name": "Camiseta100 niño GYM",
            "brand": "Quivio",
            "unit_gross_price": 5000,
            "net_amount": 12000,
            "quantity": 2,
            "tax_amount": 2000,
            "tax_rate": 20.00,
            "seller_reference": "#42-ACME",
            "seller_name": "Acme Corp",
            "is_marketplace_seller": true
          },
          {
            "type": "SHIPPING_FEES",
            "name": "Transporte",
            "net_amount": 0,
            "unit_gross_price": 0,
            "quantity": 1,
            "tax_amount": 0,
            "tax_rate": 0
          }
        ]
      }
    ]
  },
  "three_ds_authentication_options": {
    "challenge_indicator": "NO_PREFERENCE",
    "challenge_exemption": "LOW_VALUE"
  },
  "webhook": {
    "url": "https://www.example.com/payment-hook?order_id=123456789",
    "headers": [
      {
        "name": "x-custon-header",
        "values": ["lorem ipsum"]
      }
    ]
  }
}

For a detailed view of the request data, refer to the Client Session API Reference.

Information

Merchants can specify a webhook URL in the request to receive real-time updates on payment status changes.

Client Session Response

Once created, the Client Session returns additional details that were not present in the request.

Notable fields in the response:

• Status → Indicates the state of the client session.
• Capture mode → Defines whether the payment is manual or automatic.
• Eligible solutions → Lists all valid payment options for the session.
• Authorization → Details about the authorization process (only appears after payment submission).
• Widget → Contains the information needed to integrate the payment widget.

Example: Client Session Response

Client Session Response Data example

{
  "id": "76fc12e0-2226-438b-b053-8b58a8bd5984",
  "status": "CREATED",
  "expires_at": "2025-03-19T15:27:06.759Z",
  "entity_id": "fcadf8f7-2d3d-4c71-8715-ddf2c1d3fe76",
  "amount": 12000,
  "currency": "EUR",
  "allow_future_usage": false,
  "capture_mode": "MANUAL",
  "shopper_redirection_url": "https://www.example.com",
  "order": {
      "reference": "JLA123457",
      "net_amount": 12000,
      "discount_amount": 500,
      "tax_amount": 2000,
      "billing_address": {
          "gender": "MALE",
          "first_name": "Xavier",
          "middle_name": "",
          "last_name": "LEDOUX",
          "address_lines": [
              "1 rue du TEST"
          ],
          "city": "Paris",
          "postal_code": "75001",
          "country_code": "FR",
          "phone_number": "+33601020304"
      },
      "shipments": [
          {
              "net_amount": 12000,
              "estimated_delivery_date_time": "2023-10-30T13:40:00Z",
              "shipping_address": {
                  "gender": "MALE",
                  "first_name": "Xavier",
                  "middle_name": "",
                  "last_name": "LEDOUX",
                  "address_lines": [
                      "1 rue du TEST"
                  ],
                  "city": "Paris",
                  "postal_code": "75001",
                  "country_code": "FR",
                  "mobile_phone_number": "+33643547856",
                  "delivery_point_name": "home"
              },
              "item_lines": [
                  {
                      "type": "PHYSICAL",
                      "sku_reference": "34526718",
                      "name": "Chaussette",
                      "brand": "Naine",
                      "unit_gross_price": 5000,
                      "net_amount": 12000,
                      "quantity": 2,
                      "tax_amount": 2000,
                      "tax_rate": 20,
                      "seller_reference": "#42-ACME",
                      "seller_name": "Acme Corp",
                      "is_marketplace_seller": true
                  }
              ]
          }
      ]
  },
  "customer": {
      "reference": "1234567890987653212",
      "email": "[email protected]",
      "gender": "MALE",
      "first_name": "Xavier",
      "middle_name": "",
      "last_name": "LEDOUX",
      "birth_date": "1995-08-25",
      "ip_address": "203.0.113.195",
      "locale": "fr_FR",
      "account": {
          "purchase_count_last_day": 0,
          "purchase_count_last_six_months": 3,
          "purchase_count_last_year": 8,
          "authentication_method": "MERCHANT_CREDENTIALS",
          "age_indicator": "MORE_60_DAYS",
          "change_indicator": "MORE_60_DAYS",
          "password_change_indicator": "MORE_60_DAYS",
          "creation_date_time": "2017-06-15T13:30:00Z",
          "update_date_time": "2023-02-20T19:54:00Z",
          "password_update_date_time": "2023-02-20T19:54:00Z",
          "authentication_date_time": "2023-10-30T13:33:00Z"
      }
  },
  "widget": {
      "data": "eyJhcGlfdXJsIjoiaHR0cHM6Ly9hcGkucHVyc2Utc2FuZGJveC5jb2...",
      "js_url": "https://cdn.purse-sandbox.com/dropin/v3-latest/purse.js"
  },
  "links": {
      "self": {
          "method": "GET",
          "href": "https://api.purse-sandbox.com/payment/v2/client-sessions/76fc12e0-2226-438b-b053-8b58a8bd5984"
      },
      "abort": {
          "method": "POST",
          "href": "https://api.purse-sandbox.com/payment/v2/client-sessions/76fc12e0-2226-438b-b053-8b58a8bd5984/abort"
      }
  },
  "eligible_solutions": [
      {
          "partner": "oneycard",
          "method": "10x"
      },
      {
          "partner": "oneycard",
          "method": "comptant"
      },
      {
          "partner": "ingenico",
          "method": "creditcard"
      },
      {
          "partner": "oney",
          "method": "cb3x"
      },
      {
          "partner": "floa",
          "method": "cb3x"
      },
      {
          "partner": "maxxing",
          "method": "loyaltycard"
      },
      {
          "partner": "riverty",
          "method": "3x"
      },
      {
          "partner": "riverty",
          "method": "invoice"
      },
      {
          "partner": "klarna",
          "method": "installments"
      },
      {
          "partner": "illicado",
          "method": "giftcard"
      },
      {
          "partner": "payzen",
          "method": "googlepay"
      },
      {
          "partner": "slimpay",
          "method": "sepa"
      },
      {
          "partner": "adyen",
          "method": "creditcard"
      },
      {
          "partner": "scellius",
          "method": "sepainstant"
      },
      {
          "partner": "paypal",
          "method": "wallet"
      }
  ]
}

For a detailed view of the response data, refer to the Client Session API Reference.

Amount and Discount Fields

To successfully create a Client Session or a Payment, amounts sent must be consistent.

Validation Rules:

• The amount can be 0 only if allow-future-usage=true.
• The amount must be equal to or lower than order.net_amount.
• The itemLine.net_amount must be:
  (itemLine.unit_gross_price * itemLine.quantity) + itemLine.tax_amount.

Examples:

Amount and Discount Fields

To successfully create a Client Session or a Payment, amounts sent must be consistent.

Validation Rules:

• The amount can be 0 only if allow-future-usage=true.
• The amount must be equal to or lower than order.net_amount.
• The itemLine.net_amount must be:
  (itemLine.unit_gross_price * itemLine.quantity) + itemLine.tax_amount.

🛒 Without Discount

The example below represents a basket without a discount, where the sum of the item lines is 69.96 EUR.

• order.net_amount = shipments.net_amount
• order.shipment.net_amount = item_lines.net_amount
• order.tax_amount = item_lines.tax_amoun

💰 With Discount

The example below represents a basket with a 2.00 EUR discount.
The order.net_amount is impacted by the discounts.net_amount, reducing the total to 67.96 EUR.

• order.net_amount = shipments.net_amount - discounts.net_amount
• order.net_amount = item_lines.net_amount - discounts.net_amount
• order.tax_amount = item_lines.tax_amount - discounts.tax_amount
• order.shipment.net_amount = item_lines.net_amount

Without Discount

{
      "entity_id": "{{entity-id}}",
      "amount": 6996,
      "currency": "EUR",
      "order": {
        "reference": "810552538",
        "net_amount": 6996,
        "tax_amount": 1166
      },
      "customer": {
        "reference": "2010021552",
        "email": "[email protected]"
      }
}

With Discount

{
    "entity_id": "{{entity-id}}",
    "amount": 6796,
    "currency": "EUR",
    "order": {
      "reference": "810552538",
      "net_amount": 6796,
      "tax_amount": 1146,
      "discounts": [
        {
          "net_amount": 200,
          "tax_amount": 20,
          "coupon_code": "BLACKFRIDAY20"
        }
      ]
    },
    "customer": {
      "reference": "2010021552",
      "email": "[email protected]"
    }
  }

Client Session Statuses

Status	Description
CREATED	The client session has been initialized.
CHOICE_IN_PROGRESS	The customer has interacted with the payment system but has not confirmed the payment yet.
SUBMITTED	The payment has been made and submitted successfully.
EXPIRED	The client session has expired (valid for 1 hour).
ABORTED_BY_CUSTOMER	The session was explicitly canceled by the customer on the hosted page.
ABORTED_BY_MERCHANT	The session was canceled by the merchant using the Abort Client Session endpoint.

Payment Workflow

Once a client session is created, the payment process follows a structured workflow:

1️⃣ The merchant backend generates a client-session.
2️⃣ The customer selects a payment method from eligible solutions.
3️⃣ The session is submitted, and authorization begins.
4️⃣ The payment can be captured, refunded, or voided based on merchant actions.

Endpoints

Action	Description	Method	Endpoint	API Reference
Create Client Session	Initializes a payment session	POST	/v2/client-sessions	Link
Get Client Session	Retrieves session details	GET	/v2/client-sessions/{{client-session-id}}	Link
Abort Client Session	Abort a client session by Id	POST	/v2/client-sessions/{id}/abort	Link