Skip to main content

Your first Payment with Purse

The Purse API simplifies the integration between merchants and payment providers by introducing business logic to handle failed authorizations, multiple payment methods, and essential operations like capture, void, and refund.

This guide walks you through a basic payment flow, step by step :

  • Authenticate with the API using OAuth2
  • Create a client session to start a payment
  • Integrate the Purse Checkout widget in your front-end
  • Handle customer redirection after the payment
  • Perform post-payment operations like capture, refund, or void

1. Authentication - Retrieve Access Token​

Before making any API calls, you must authenticate by obtaining an OAuth2 Access Token.

Token Authentication

See Authentication Guide for details on generating your token.

2. Create a Client Session​

The client session is the first key element of the payment process. It allows the merchant to centralize all relevant order information and gives him access to the necessary elements to proceed with the payment process.

Client Session Data

⚠ You will need to provide various data from the customer and their order to ensure your payment is accepted by our PSPs.
Some data are mandatory to process the payment.

See our Partners section to check the minimal data required.
It is advised to provide as much information as possible to maximize your conversion rate and compatibility with all your payment providers.

Create Client Session

Key Data Response​

  • Client-session ID → Used to track the session. (Path : id)
  • Widget URL → Used to display the payment form. ( Path : widget.js_url)
  • Widget Data → Data to be passed to the widget. ( Path : widget.data)

Example Request​

curl -X POST 'https://api.purse-sandbox.com/payment/v2/client-sessions'
--header 'Content-Type: application/json'
--header "x-api-key: ${API_KEY}"
--header "Authorization: Bearer ${ACCESS_TOKEN}"
--data-raw "[...]"

Example Response​

  {
    "id": "aa30c404-bafe-4058-8d71-dec8e5a8b0f0",
    "status": "CREATED",
    "expires_at": "2025-04-08T14:10:31.616Z",
    "amount": 12000,
    "currency": "EUR",
    "shopper_redirection_url": "https://www.example.com",
    "widget": {
      "js_url": "https://cdn.purse-sandbox.com/dropin/v3-latest/purse.js",
      "data": "eyJhcGlfdXJsIjoiaHR0cHM6Ly9..."
    },
    [...]
}
Client Session Reference

To get a better understand of the Client Session, see the Client Session Reference.

3. Integrate Purse Checkout​

Purse Checkout is the front-end interface that allows merchants to seamlessly collect payment details and process transactions securely.

When initializing a payment session, you will receive a widget.js_url field and widget.data field in the response, which must be used to integrate the Purse Checkout into your payment page.

A quick and simple integration should give you something like below

To integrate our checkout and test your payment, you can look at this guide

4. Handling Customer Redirection After Payment​

Once the payment process is complete, the customer is redirected to the shopper_redirection_url provided during the client session creation.

Redirection URL length

Due to the maximum URL length a web browser can handle (the maximum URL length varies between different browsers and web servers), we suggest the merchant to have a shopper_redirection_url to be as short as possible.

Purse automatically appends a purse-redirection-data parameter to the URL, which contains key payment details such as:

  • client_session_id → Identifies the session.
  • payment_id → The unique ID of the payment.
  • authorization_status → Indicates if the payment was AUTHORIZED, DECLINED, PENDING or another status (See Authorization Status Reference).
  • client_session_status → Indicates if the session was SUBMITTED, ABORTED_BY_CUSTOMER or ABORTED_BY_MERCHANT.
Purse Redirection is signed

The purse-redirection-data is signed to ensure its authenticity and prevent tampering.
You must validate the signature on your server before processing the redirection result.
For additional informations on the signature and examples, see the Redirection Reference.

5. Retrieving Payment Status via API​

To check the status of a payment, you can use the Get Payment endpoint.
It will allows you to retrieve the payment details and its current status.

Get Payment Data

GetPayment Response​

Response Data
{
    "id": "bcb2c3ff-f9a2-4f60-8913-fa94e4d41f27",
    "entity_id": "74a871c8-8a38-423f-80c0-5cabd9a18264",
    "client_session_id": "33d30741-3c55-40f7-8033-b2c9f473baba",
    "created_at": "2025-04-09T12:52:14.281Z",
    "order_reference": "JLA123457",
    "order": {
          [...]
        },
        "shipments": [
            [...]
        ]
    },
    "customer": {
        [...]
    },
    "overview": {
        "consumed": "NOT",
        "captured": "NOT",
        "voided": "NOT",
        "refunded": "NOT"
    },
    "amount": 12000,
    "currency": "EUR",
    "allow_future_usage": false,
    "capture_mode": "MANUAL",
    "authorization": {
        "updated_at": "2025-04-09T12:52:17.824Z",
        "status": "AUTHORIZED",
        "partner_transactions": [
            {
                "partner": "ingenico",
                "method": "creditcard",
                "id": "7c1d3b70-6002-41a0-b6e9-9bf2a035920c",
                "amount": 12000,
                "remaining_amount": 12000,
                "created_at": "2025-04-09T12:52:14.28Z",
                "updated_at": "2025-04-09T12:52:17.824Z",
                "partner_status": "PENDING_CAPTURE",
                "partner_status_description": "Your authorisation request was successful, but you still need to capture it to receive the funds",
                "status": "AUTHORIZED",
                "card": {
                    "bin": "424242",
                    "last_four_digits": "4242",
                    "holder_name": "gffgfd",
                    "expiry_month": "01",
                    "expiry_year": "2026",
                    "selected_network": "VISA",
                    "three_ds": {
                        "eci": "05",
                        "flow": "CHALLENGE",
                        "ds_transaction_id": "D7B76870-0765-4F36-A9F1-C5B23D35D3E2",
                        "acs_transaction_id": "A4DCDBC9-98CB-450D-9535-3D6BED79C2A5"
                    },
                    "type": "VISA_CREDIT"
                }
            }
        ]
    },
    "captures": [],
    "voids": [],
    "refunds": [],
    "split": [
        {
            "partner": "ingenico",
            "method": "creditcard",
            "amount": 12000
        }
    ],
    "amounts": {
        "authorize_pending": 0,
        "total_authorized": 12000,
        "total_captured": 0,
        "available_to_capture": 12000,
        "total_refunded": 0,
        "available_to_refund": 0,
        "total_voided": 0,
        "available_to_void": 12000
    },
    [...]
}

6. Additional Data​

While most merchants only need the core payment response fields, some technical use cases — such as advanced monitoring or PSP-specific reconciliation — may require accessing more detailed information.

One such example is the list of partner_transactions, available in both client sessions and payments.
These entries contain useful information such as:

  • The PSP name (partner)
  • The payment method used
  • The raw PSP status and our standardized status
  • Card or wallet metadata (when applicable)

To learn more, see the dedicated page: Partner Transactions

Good to know

You don't need to handle partner_transactions for most use cases, we advise to use the data Purse provides but they can be valuable for some specific use cases.

Next Step: Understanding the Payment Resource & Operations​

Once your payment is AUTHORIZED, we should explore the Payment object in detail. It contains all the information related to the payment, including its status, amounts, and other relevant data.

Furthermore, we are now able to perform essential operations on it to manage the payment lifecycle, such as:

  • Capture a payment, confirming the transaction
  • Refund a payment, returning funds to the customer
  • Void a payment, cancelling the transaction before capture

Check the Payment Operations Guide