PayIntelliPayIntelli
API reference

Pi Checkout

E-commerce checkout and payment processing API.

Base URL

https://checkout-api.payintelli.com

Endpoints

8 documented routes

Overview

The Checkout API provides endpoints to create and manage checkout sessions for payment processing.

Base Path: /{culture}/api/v1/checkout

Authentication

All requests must include the following headers unless noted otherwise:

HeaderRequiredDescription
pi-api-keyYes (most endpoints)Your API key for authenticating requests
pi-client-idYes (create & status)Your client identifier
pi-correlation-idNoOptional identifier for correlating requests on your side

Endpoints

1. Create Checkout

POST

Endpoints

Description

Initiates a new checkout session and returns a URL to redirect the customer to the hosted payment page.

Status: 201 Created

Redirect the customer to the checkoutUrl to complete their payment.

Common validation failures:

  • transaction.amount is less than 0.01
  • notification.webhookUrl is not HTTPS, is malformed, or points to a local address
  • userDetails.email is not a valid email address
  • userDetails.phone does not match the expected international format
  • pi-client-id is missing, non-numeric, or invalid

Endpoint Path

/{culture}/api/v1/checkout/create

Headers

HeaderRequiredDescription
`pi-api-key`RequiredYour API key for authenticating requests
`pi-client-id`RequiredYour client identifier
`pi-correlation-id`OptionalOptional identifier for correlating requests on your side

Parameters

ParameterTypeRequiredDescription
`transaction.amount`numberRequiredMust be greater than or equal to `1`
`transaction.currency`stringRequiredISO 4217 currency code (e.g. `USD`). Normalized to uppercase.
`clientOrderDetails.clientOrderId`stringRequiredYour unique identifier for the order
`clientOrderDetails.description`stringRequiredA short description of the purchase
`userDetails.firstName`stringRequiredThe customer's first name
`userDetails.lastName`stringRequiredThe customer's last name
`userDetails.email`stringRequiredMust be a valid email address
`userDetails.clientUserId`stringRequiredYour unique identifier for the user
`userDetails.phone`stringRequiredInternational format (e.g. `+441234567890`)
`userDetails.address`stringRequiredThe customer's primary billing address
`userDetails.city`stringRequiredThe city for the billing address
`userDetails.state`stringRequiredThe state or province for the billing address
`userDetails.country`stringRequiredISO 3166-1 alpha-2 country code (e.g. `GB`)
`userDetails.postalCode`stringRequiredThe postal code for the billing address
`notification.successUrl`stringRequiredHTTPS URL to redirect the customer after successful payment
`notification.cancelUrl`stringRequiredHTTPS URL to redirect the customer if they cancel
`notification.webhookUrl`stringRequiredHTTPS URL to receive payment event notifications. Must not point to a local or private address.

Request Body

{
  "transaction": {
    "amount": 100.00,
    "currency": "USD"
  },
  "clientOrderDetails": {
    "clientOrderId": "ORDER-123",
    "description": "Purchase of widgets"
  },
  "userDetails": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "clientUserId": "user-789",
    "phone": "+441234567890",
    "address": "12 Example Street",
    "city": "London",
    "state": "Greater London",
    "country": "GB",
    "postalCode": "SW1A 1AA"
  },
  "notification": {
    "successUrl": "https://merchant.example.com/success",
    "cancelUrl": "https://merchant.example.com/cancel",
    "webhookUrl": "https://merchant.example.com/webhook"
  }
}

Response Body

{
  "checkoutId": "1234567890123456789",
  "checkoutUrl": "https://checkout.example.com/en/checkoutpage?checkoutId=1234567890123456789&token=..."
}

2. Get Checkout Status

GET

Endpoints

Description

Retrieves the current status of a checkout session.

Status: 200 OK

Common lookup issues:

  • checkoutId is not a valid numeric identifier
  • pi-client-id is missing or does not match the session's owner
  • The checkout session cannot be resolved for the requesting client

Endpoint Path

/{culture}/api/v1/checkout/status/{checkoutId}

Headers

HeaderRequiredDescription
`pi-api-key`RequiredYour API key for authenticating requests
`pi-client-id`RequiredYour client identifier

Parameters

ParameterTypeRequiredDescription
`checkoutId`stringOptionalThe ID returned when the checkout was created

Response Body

{
  "checkoutId": "1234567890123456789",
  "status": "PENDING",
  "transaction": {
    "amount": 100.00,
    "currency": "USD"
  }
}

3. Get Checkout Details

GET

Endpoints

Description

Retrieves the full details of a checkout session, including user and order information.

Status: 200 OK

Common lookup issues:

  • The checkout session belongs to a different client account
  • checkoutId is syntactically valid but does not exist
  • pi-client-id is provided but does not match the session's owner

Endpoint Path

/{culture}/api/v1/checkout/details/{checkoutId}

Headers

HeaderRequiredDescription
`pi-api-key`OptionalYour API key for authenticating requests
`pi-client-id`OptionalYour client identifier

Parameters

ParameterTypeRequiredDescription
`checkoutId`stringOptionalThe ID returned when the checkout was created

Response Body

{
  "checkoutId": "1234567890123456789",
  "status": "PENDING",
  "transaction": {
    "amount": 100.00,
    "currency": "USD"
  },
  "clientOrderDetails": {
    "clientOrderId": "ORDER-123",
    "description": "Purchase of widgets"
  },
  "userDetails": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "clientUserId": "user-789",
    "phone": "+441234567890",
    "address": "12 Example Street",
    "city": "London",
    "state": "Greater London",
    "country": "GB",
    "postalCode": "SW1A 1AA"
  },
  "additionalData": {
    "correlationId": "corr-abc-123"
  }
}

Notes

  • The status and details endpoints are read-only.
  • After a successful create call, use the returned checkoutUrl to redirect the customer to the hosted payment page.
  • All API keys and client IDs are issued during onboarding. Contact support if you need new credentials.

Webhook integration

When a checkout is created, the request must include notification.webhookUrl. This URL is the destination for checkout lifecycle notifications.

CreateCheckoutRequest.notification fields:

  • successUrl: redirect URL for successful checkout completion
  • cancelUrl: redirect URL for cancelled checkout
  • webhookUrl: destination for webhook notifications

Webhook URL requirements

Webhook integration

Description

The webhook URL must:

  • be present and non-empty
  • be a valid HTTPS URI
  • include a valid, publicly routable host
  • not use local or reserved addresses such as localhost, .local, .internal, .lan, or private IP ranges

Webhook delivery

Webhook integration

Description

Webhook notifications are delivered asynchronously after checkout status changes. Your endpoint should accept JSON POST requests and return a 2xx response to acknowledge successful delivery.

Sample webhook payload

Webhook integration

Description

A webhook payload may contain fields similar to the following:

Typical payload fields:

  • eventType: the checkout lifecycle event
  • checkoutId: unique checkout session identifier
  • clientOrderId: merchant-supplied order identifier
  • transactionId: payment transaction identifier
  • status: final status of the checkout
  • timestamp: event time in ISO 8601 UTC format

Retry and delivery expectations

Webhook integration

Description

  • Notifications are retried if your endpoint is temporarily unavailable.
  • Your receiver should be idempotent, since duplicate deliveries can occur.
  • A successful delivery is confirmed by any 2xx HTTP response.

Error handling

Webhook integration

Description

  • If the webhook URL is invalid or unreachable, the checkout service may reject the checkout creation request.
  • If your endpoint returns non-2xx responses, delivery retries may be attempted.