Create a Payment

Overview

Accepting a payment in kadosei is a three-step process:

1. Call the kadosei API to create a payment session

2. Redirect your customer to the checkoutUrl returned in the response

3. Handle the outcome via webhooks or by polling the session status endpoint

Payment sessions use your application API key for authentication, not a JWT. Make sure you are using your ks_live_ key in the Authorization header.

Before you begin

You need an active application with at least one payment provider configured. If you have not done this yet, see [Get Started] and [Applications & API Keys].

Create a session

Submitting a valid session request causes kadosei to select a payment provider, create a checkout session with that provider, and return a hosted checkout URL for your customer.

Every session creation request must include an Idempotency-Key header containing a client-generated UUID v4. This allows you to safely retry a request without creating duplicate sessions. Use a fresh key for each new transaction.

Request headers

POST /api/v1/sessions

{
  "orderReference": "ORD-2024-001",
  "paymentMethod": "card",
  "currency": "AUD",
  "locale": "en_AU",
  "amount": {
    "total": 140.76,
    "shipping": 9.95,
    "tax": 11.81
  },
  "orderItems": [
    {
      "name": "Wireless Headphones",
      "sku": "WH-100",
      "quantity": 1,
      "unitPrice": 119.00
    },
    {
      "name": "Carry Case",
      "sku": "CC-200",
      "quantity": 1,
      "unitPrice": 11.00
    }
  ],
  "customer": {
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane.smith@example.com",
    "phone": "+61412345678",
    "billingAddress": {
      "line1": "123 Collins Street",
      "line2": "Level 5",
      "city": "Melbourne",
      "state": "VIC",
      "postalCode": "3000",
      "country": "AU"
    }
  },
  "redirectUrls": {
    "success": "https://merchant.example.com/checkout/success",
    "failure": "https://merchant.example.com/checkout/failure"
  }
}

amount.total must equal the sum of all order item prices (unit price × quantity), plus shipping and tax if provided. The request will be rejected if the values do not reconcile.

orderItems requires at least one item. sku is optional per item.

customer.billingAddress is required. shippingAddress is optional and only needed if it differs from billing.

locale and shipping are optional. additionalInformation can carry custom metadata such as campaignId and referralCode.

{
  "sessionId": "e4b8c1a2-b088-4e79-99ad-2c3e0fa3f1b9",
  "checkoutUrl": "https://checkout.kadosei.com/pay/e4b8c1a2-b088-4e79-99ad-2c3e0fa3f1b9",
  "status": "PENDING",
  "expiresAt": "2024-01-15T12:00:00Z",
  "createdAt": "2024-01-15T11:00:00Z"
}

Errors

Redirect your customer

Once you have a checkoutUrl, redirect your customer to it. kadosei hosts the checkout experience and forwards the customer to the appropriate payment provider.

When the customer completes or abandons the payment, they are redirected to the success or failure URL you provided in the session request.

Do not parse or store the checkoutUrl structure as it may change. Treat it as an opaque redirect target.

Check session status

You can retrieve the current state of a session at any time using the session ID.

GET /api/v1/sessions/{sessionId}

{
  "id": "e4b8c1a2-b088-4e79-99ad-2c3e0fa3f1b9",
  "orderReference": "ORD-2024-001",
  "status": "SUCCEEDED",
  "paymentMethod": "card",
  "providerName": "stripe",
  "failureReason": null,
  "expiresAt": "2024-01-15T12:00:00Z",
  "createdAt": "2024-01-15T11:00:00Z",
  "updatedAt": "2024-01-15T11:30:00Z"
}

Errors

Session statuses

What's next

Set up webhooks to receive real-time notifications when a session status changes, rather than polling the status endpoint.