Create a checkout session

Checkout sessions give a payer a temporary context to complete a hosted payment. Use them when the same payment link can be opened by different customers, when customer details are collected at checkout time, or when your frontend needs to refresh an expired session token.

Note

Use the payment link as the reusable commercial offer. Use the checkout session as the individual payer session.

Flow

01

Create link

Define amount, allowed methods, destination, and URLs.

02

Create session

Attach customer context to the checkout token.

03

Submit payment

The payer chooses a method and creates the checkout payment.

04

Refresh if needed

Refresh the checkout token when the UI expires.

Create the session

Request

HTTPcurlJavaScriptPythonGoRust

POST /sandbox/checkout-sessions HTTP/1.1
Host: api.conomyhq.com
x-api-key: {YOUR_API_KEY}
Authorization: Bearer {ACCESS_TOKEN}
conomyhq-api-version: 24-04-2025
User-Agent: MyApp/1.0
Content-Type: application/json
Accept: application/json

{
  "checkoutToken": "<CHECKOUT_TOKEN>",
  "customer": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "documentType": "CC",
    "documentNumber": "1000000000"
  }
}

curl -X POST 'https://api.conomyhq.com/sandbox/checkout-sessions' \
  -H 'x-api-key: {YOUR_API_KEY}' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'conomyhq-api-version: 24-04-2025' \
  -H 'User-Agent: MyApp/1.0' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "checkoutToken": "<CHECKOUT_TOKEN>",
    "customer": {
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane@example.com",
      "documentType": "CC",
      "documentNumber": "1000000000"
    }
  }'

const response = await fetch('https://api.conomyhq.com/sandbox/checkout-sessions', {
  method: 'POST',
  headers: {
    'x-api-key': '{YOUR_API_KEY}',
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    "checkoutToken": "<CHECKOUT_TOKEN>",
    "customer": {
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane@example.com",
      "documentType": "CC",
      "documentNumber": "1000000000"
    }
  }),
});

const data = await response.json();

import requests

payload = {
  "checkoutToken": "<CHECKOUT_TOKEN>",
  "customer": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "documentType": "CC",
    "documentNumber": "1000000000"
  }
}

response = requests.post(
    'https://api.conomyhq.com/sandbox/checkout-sessions',
    headers={
    'x-api-key': '{YOUR_API_KEY}',
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    },
    json=payload,
)

data = response.json()

package main

import (
	"bytes"
	"net/http"
)

func main() {
	payload := []byte(`{
  "checkoutToken": "<CHECKOUT_TOKEN>",
  "customer": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "documentType": "CC",
    "documentNumber": "1000000000"
  }
}`)
	body := bytes.NewReader(payload)
	req, _ := http.NewRequest("POST", "https://api.conomyhq.com/sandbox/checkout-sessions", body)
	req.Header.Set("x-api-key", "{YOUR_API_KEY}")
	req.Header.Set("Authorization", "Bearer {ACCESS_TOKEN}")
	req.Header.Set("conomyhq-api-version", "24-04-2025")
	req.Header.Set("User-Agent", "MyApp/1.0")
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Accept", "application/json")

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
}

use reqwest::Client;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let payload = json!({
  "checkoutToken": "<CHECKOUT_TOKEN>",
  "customer": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "documentType": "CC",
    "documentNumber": "1000000000"
  }
});

    let response = client
        .post("https://api.conomyhq.com/sandbox/checkout-sessions")
        .header("x-api-key", "{YOUR_API_KEY}")
        .header("Authorization", "Bearer {ACCESS_TOKEN}")
        .header("conomyhq-api-version", "24-04-2025")
        .header("User-Agent", "MyApp/1.0")
        .header("Content-Type", "application/json")
        .header("Accept", "application/json")
        .json(&payload)
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    Ok(())
}

Response

201

{
  "id": "<CHECKOUT_SESSION_ID>",
  "checkoutToken": "<CHECKOUT_TOKEN>",
  "status": "ATTEMPT",
  "currency": "CLP",
  "url": "https://checkout.conomyhq.com/<CHECKOUT_TOKEN>"
}

Create the checkout payment

Request

HTTPcurlJavaScriptPythonGoRust

POST /sandbox/checkout-sessions/{CHECKOUT_SESSION_ID}/payments HTTP/1.1
Host: api.conomyhq.com
x-api-key: {YOUR_API_KEY}
Authorization: Bearer {ACCESS_TOKEN}
conomyhq-api-version: 24-04-2025
User-Agent: MyApp/1.0
Content-Type: application/json
Accept: application/json

{
  "paymentMethod": "ETPAY",
  "customer": {
    "firstName": "Jane",
    "email": "jane@example.com"
  }
}

curl -X POST 'https://api.conomyhq.com/sandbox/checkout-sessions/{CHECKOUT_SESSION_ID}/payments' \
  -H 'x-api-key: {YOUR_API_KEY}' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'conomyhq-api-version: 24-04-2025' \
  -H 'User-Agent: MyApp/1.0' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "paymentMethod": "ETPAY",
    "customer": {
      "firstName": "Jane",
      "email": "jane@example.com"
    }
  }'

const response = await fetch('https://api.conomyhq.com/sandbox/checkout-sessions/{CHECKOUT_SESSION_ID}/payments', {
  method: 'POST',
  headers: {
    'x-api-key': '{YOUR_API_KEY}',
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    "paymentMethod": "ETPAY",
    "customer": {
      "firstName": "Jane",
      "email": "jane@example.com"
    }
  }),
});

const data = await response.json();

import requests

payload = {
  "paymentMethod": "ETPAY",
  "customer": {
    "firstName": "Jane",
    "email": "jane@example.com"
  }
}

response = requests.post(
    'https://api.conomyhq.com/sandbox/checkout-sessions/{CHECKOUT_SESSION_ID}/payments',
    headers={
    'x-api-key': '{YOUR_API_KEY}',
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    },
    json=payload,
)

data = response.json()

package main

import (
	"bytes"
	"net/http"
)

func main() {
	payload := []byte(`{
  "paymentMethod": "ETPAY",
  "customer": {
    "firstName": "Jane",
    "email": "jane@example.com"
  }
}`)
	body := bytes.NewReader(payload)
	req, _ := http.NewRequest("POST", "https://api.conomyhq.com/sandbox/checkout-sessions/{CHECKOUT_SESSION_ID}/payments", body)
	req.Header.Set("x-api-key", "{YOUR_API_KEY}")
	req.Header.Set("Authorization", "Bearer {ACCESS_TOKEN}")
	req.Header.Set("conomyhq-api-version", "24-04-2025")
	req.Header.Set("User-Agent", "MyApp/1.0")
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Accept", "application/json")

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
}

use reqwest::Client;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let payload = json!({
  "paymentMethod": "ETPAY",
  "customer": {
    "firstName": "Jane",
    "email": "jane@example.com"
  }
});

    let response = client
        .post("https://api.conomyhq.com/sandbox/checkout-sessions/{CHECKOUT_SESSION_ID}/payments")
        .header("x-api-key", "{YOUR_API_KEY}")
        .header("Authorization", "Bearer {ACCESS_TOKEN}")
        .header("conomyhq-api-version", "24-04-2025")
        .header("User-Agent", "MyApp/1.0")
        .header("Content-Type", "application/json")
        .header("Accept", "application/json")
        .json(&payload)
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    Ok(())
}

Response

201

{
  "id": "<CHECKOUT_PAYMENT_ID>",
  "checkoutSessionId": "<CHECKOUT_SESSION_ID>",
  "status": "CREATED"
}

Refresh an expired token

Request

HTTPcurlJavaScriptPythonGoRust

POST /sandbox/checkout-sessions/token/{CHECKOUT_TOKEN}/refresh HTTP/1.1
Host: api.conomyhq.com
x-api-key: {YOUR_API_KEY}
Authorization: Bearer {ACCESS_TOKEN}
conomyhq-api-version: 24-04-2025
User-Agent: MyApp/1.0
Accept: application/json

curl -X POST 'https://api.conomyhq.com/sandbox/checkout-sessions/token/{CHECKOUT_TOKEN}/refresh' \
  -H 'x-api-key: {YOUR_API_KEY}' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'conomyhq-api-version: 24-04-2025' \
  -H 'User-Agent: MyApp/1.0' \
  -H 'Accept: application/json'

const response = await fetch('https://api.conomyhq.com/sandbox/checkout-sessions/token/{CHECKOUT_TOKEN}/refresh', {
  method: 'POST',
  headers: {
    'x-api-key': '{YOUR_API_KEY}',
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Accept': 'application/json',
  },
});

const data = await response.json();

import requests

response = requests.post(
    'https://api.conomyhq.com/sandbox/checkout-sessions/token/{CHECKOUT_TOKEN}/refresh',
    headers={
    'x-api-key': '{YOUR_API_KEY}',
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Accept': 'application/json',
    },
)

data = response.json()

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.conomyhq.com/sandbox/checkout-sessions/token/{CHECKOUT_TOKEN}/refresh", nil)
	req.Header.Set("x-api-key", "{YOUR_API_KEY}")
	req.Header.Set("Authorization", "Bearer {ACCESS_TOKEN}")
	req.Header.Set("conomyhq-api-version", "24-04-2025")
	req.Header.Set("User-Agent", "MyApp/1.0")
	req.Header.Set("Accept", "application/json")

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
}

use reqwest::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let response = client
        .post("https://api.conomyhq.com/sandbox/checkout-sessions/token/{CHECKOUT_TOKEN}/refresh")
        .header("x-api-key", "{YOUR_API_KEY}")
        .header("Authorization", "Bearer {ACCESS_TOKEN}")
        .header("conomyhq-api-version", "24-04-2025")
        .header("User-Agent", "MyApp/1.0")
        .header("Accept", "application/json")
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    Ok(())
}

Response

200

{
  "id": "<CHECKOUT_SESSION_ID>",
  "checkoutToken": "<CHECKOUT_TOKEN>",
  "status": "ATTEMPT"
}