Create a checkout session

POST

/checkout/sessions

const url = 'https://apisandbox.puurk.com/checkout/sessions';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"oid":"example","amount":1,"down_payment":1,"items":[{"service_id":"example","quantity":1}],"services":[{"name":"example","service_id":"example","quantity":1,"amount":1}],"offer_id":"example","customer":{"name":"example","email":"example","phone":"example"},"return_url":"example","cancel_url":"example","metadata":{}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://apisandbox.puurk.com/checkout/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "oid": "example", "amount": 1, "down_payment": 1, "items": [ { "service_id": "example", "quantity": 1 } ], "services": [ { "name": "example", "service_id": "example", "quantity": 1, "amount": 1 } ], "offer_id": "example", "customer": { "name": "example", "email": "example", "phone": "example" }, "return_url": "example", "cancel_url": "example", "metadata": {} }'

Create a hosted checkout session for a customer. Send oid with either amount (your price, in cents) or items (catalog service ids and quantities, priced by Puurk), or send offer_id for an existing offer. With items, the amount is the sum of unit_price x quantity, the down payment is the sum of each service’s down payment x quantity, and, when the organization uses term caps, plan length is capped by the largest term_cap among the services. Sending items together with amount, down_payment or services, or together with offer_id, is a 400. Callable with a service token or, from a browser, with a publishable client, which may only create sessions from items (never an amount) and whose Idempotency-Key header is ignored. A publishable client is an API client issued with POST /auth/clients whose scope is {resource: 'checkout', oid: <org>, actions: ['read', 'write'], public: true} and whose allowed_origins list is non-empty. Pass its id as client_id (or the X-Puurk-Client-Id header) instead of a bearer token. No secret is used, so the request must come from a browser Origin in allowed_origins and target the one organization the scope names.

Authorizations

service_token
None

Parameters

Query Parameters

client_id

string

Publishable client id, for browser calls with no bearer token. Omit when calling with a service token.

Request Body^required

Request body

application/json

object

oid

Organization ID. Required with amount or items.

string

amount

Total amount in cents. Not allowed with items.

integer

down_payment

Down payment in cents. Not allowed with items.

integer

items

Catalog services to price, as an alternative to amount. Puurk sets the amount, down payment and plan-length cap from the services. Not allowed with amount, down_payment, services or offer_id. The only pricing input a publishable client may send.

Array<object>

<= 20 items

object

service_id

required

Catalog service ID

string

quantity

Units of the service. Repeated service ids are merged.

integer

default: 1 >= 1 <= 10

services

Informational line items for an amount-based session. Not allowed with items.

Array<object>

object

name

string

service_id

string

quantity

number

amount

Amount in cents

integer

offer_id

Existing pending offer to check out, instead of oid + amount or items

string

customer

object

name

string

email

string

phone

string

return_url

string

cancel_url

string

metadata

object

key

additional properties

any

Responses

200

Existing session returned for a repeated Idempotency-Key

application/json

object

string

oid

Organization ID

string

partner_id

string

offer_id

string

customer

object

name

string

email

string

phone

string

amount

Total amount in cents

integer

services

Array<object>

object

name

string

service_id

string

quantity

number

amount

Amount in cents

integer

plans

Array<object>

object

offer_id

Offer these terms belong to

string

uid

User the terms were generated for

string

down_payment

Down payment in cents

number

financed_amount

Amount financed in cents

number

provider_premium_share

Provider’s share of the premium as a fraction between 0 and 1

number

nullable

term_length

Plan length in months

number

monthly_premium

Premium charged per month in cents

number

monthly_provider_premium

Provider share of the monthly premium in cents

number

nullable

monthly_puurk_premium

Puurk share of the monthly premium in cents

number

nullable

monthly_principal

Principal per month in cents

number

monthly_fees

Fees included in each monthly payment in cents

number

nullable

monthly_payout_fees

Payout fees per month in cents

number

nullable

monthly_provider_fees

Provider fees per month in cents

number

nullable

monthly_payment

Monthly payment in cents

number

monthly_opportunity

Monthly opportunity for the provider in cents

number

nullable

total_amount

Total paid over the plan in cents

number

total_premium

Total premium over the plan in cents

number

total_provider_premium

Provider share of the total premium in cents

number

nullable

total_puurk_premium

Puurk share of the total premium in cents

number

nullable

total_principal

Total principal (down payment plus financed amount) in cents

number

total_fees

Total fees over the plan in cents

number

nullable

total_payout_fees

Total payout fees over the plan in cents

number

nullable

total_provider_fees

Total provider fees over the plan in cents

number

nullable

total_opportunity

Total opportunity for the provider in cents

number

nullable

selected_plan

object

offer_id

Offer these terms belong to

string

uid

User the terms were generated for

string

down_payment

Down payment in cents

number

financed_amount

Amount financed in cents

number

provider_premium_share

Provider’s share of the premium as a fraction between 0 and 1

number

nullable

term_length

Plan length in months

number

monthly_premium

Premium charged per month in cents

number

monthly_provider_premium

Provider share of the monthly premium in cents

number

nullable

monthly_puurk_premium

Puurk share of the monthly premium in cents

number

nullable

monthly_principal

Principal per month in cents

number

monthly_fees

Fees included in each monthly payment in cents

number

nullable

monthly_payout_fees

Payout fees per month in cents

number

nullable

monthly_provider_fees

Provider fees per month in cents

number

nullable

monthly_payment

Monthly payment in cents

number

monthly_opportunity

Monthly opportunity for the provider in cents

number

nullable

total_amount

Total paid over the plan in cents

number

total_premium

Total premium over the plan in cents

number

total_provider_premium

Provider share of the total premium in cents

number

nullable

total_puurk_premium

Puurk share of the total premium in cents

number

nullable

total_principal

Total principal (down payment plus financed amount) in cents

number

total_fees

Total fees over the plan in cents

number

nullable

total_payout_fees

Total payout fees over the plan in cents

number

nullable

total_provider_fees

Total provider fees over the plan in cents

number

nullable

total_opportunity

Total opportunity for the provider in cents

number

nullable

payment_intent_id

string

contract_id

string

status

string

Allowed values: pending plan_selected payment_ready completed expired canceled

return_url

string

cancel_url

string

metadata

object

key

additional properties

any

idempotency_key

string

expires_at

string format: date-time

created_at

string format: date-time

updated_at

string format: date-time

Example

{
  "status": "pending"
}

201

Checkout session created

application/json

object

string

oid

Organization ID

string

partner_id

string

offer_id

string

customer

object

name

string

email

string

phone

string

amount

Total amount in cents

integer

services

Array<object>

object

name

string

service_id

string

quantity

number

amount

Amount in cents

integer

plans

Array<object>

object

offer_id

Offer these terms belong to

string

uid

User the terms were generated for

string

down_payment

Down payment in cents

number

financed_amount

Amount financed in cents

number

provider_premium_share

Provider’s share of the premium as a fraction between 0 and 1

number

nullable

term_length

Plan length in months

number

monthly_premium

Premium charged per month in cents

number

monthly_provider_premium

Provider share of the monthly premium in cents

number

nullable

monthly_puurk_premium

Puurk share of the monthly premium in cents

number

nullable

monthly_principal

Principal per month in cents

number

monthly_fees

Fees included in each monthly payment in cents

number

nullable

monthly_payout_fees

Payout fees per month in cents

number

nullable

monthly_provider_fees

Provider fees per month in cents

number

nullable

monthly_payment

Monthly payment in cents

number

monthly_opportunity

Monthly opportunity for the provider in cents

number

nullable

total_amount

Total paid over the plan in cents

number

total_premium

Total premium over the plan in cents

number

total_provider_premium

Provider share of the total premium in cents

number

nullable

total_puurk_premium

Puurk share of the total premium in cents

number

nullable

total_principal

Total principal (down payment plus financed amount) in cents

number

total_fees

Total fees over the plan in cents

number

nullable

total_payout_fees

Total payout fees over the plan in cents

number

nullable

total_provider_fees

Total provider fees over the plan in cents

number

nullable

total_opportunity

Total opportunity for the provider in cents

number

nullable

selected_plan

object

offer_id

Offer these terms belong to

string

uid

User the terms were generated for

string

down_payment

Down payment in cents

number

financed_amount

Amount financed in cents

number

provider_premium_share

Provider’s share of the premium as a fraction between 0 and 1

number

nullable

term_length

Plan length in months

number

monthly_premium

Premium charged per month in cents

number

monthly_provider_premium

Provider share of the monthly premium in cents

number

nullable

monthly_puurk_premium

Puurk share of the monthly premium in cents

number

nullable

monthly_principal

Principal per month in cents

number

monthly_fees

Fees included in each monthly payment in cents

number

nullable

monthly_payout_fees

Payout fees per month in cents

number

nullable

monthly_provider_fees

Provider fees per month in cents

number

nullable

monthly_payment

Monthly payment in cents

number

monthly_opportunity

Monthly opportunity for the provider in cents

number

nullable

total_amount

Total paid over the plan in cents

number

total_premium

Total premium over the plan in cents

number

total_provider_premium

Provider share of the total premium in cents

number

nullable

total_puurk_premium

Puurk share of the total premium in cents

number

nullable

total_principal

Total principal (down payment plus financed amount) in cents

number

total_fees

Total fees over the plan in cents

number

nullable

total_payout_fees

Total payout fees over the plan in cents

number

nullable

total_provider_fees

Total provider fees over the plan in cents

number

nullable

total_opportunity

Total opportunity for the provider in cents

number

nullable

payment_intent_id

string

contract_id

string

status

string

Allowed values: pending plan_selected payment_ready completed expired canceled

return_url

string

cancel_url

string

metadata

object

key

additional properties

any

idempotency_key

string

expires_at

string format: date-time

created_at

string format: date-time

updated_at

string format: date-time

Example

{
  "status": "pending"
}

400

Invalid input (including items sent with amount, down_payment, services or offer_id)

401

Unauthorized

403

Forbidden (no checkout scope on the organization, origin not allowed, or a publishable client sent an amount instead of items)

422

A service is not available for online checkout, or the session cannot be created

Create a checkout session

Authorizations

Parameters

Query Parameters

Request Bodyrequired

Responses

200

Example

201

Example

400

401

403

422

Request Body^required