API Reference / Checkout Sessions REST

Actions

Creates a checkout session for a payment link.

POST/checkout-sessions

Create checkout session

Headers

Authorizationstringrequired

Bearer access token returned by the authentication endpoint.

x-api-keystringrequired

The API key used for authentication when making requests to the API Gateway.

conomyhq-api-versionstring

API version selector for Conomy endpoints. Use 24-04-2025 for the current version.

User-Agentstringrequired

Identifies the application making the request.

Request body

checkoutTokenstringrequired

Reference for checkout url

itemsobject[]required

List of items to pay for

preTaxAmountstringrequired

The amount of the item

totalAmountstringrequired

amount + tax.amount, if no tax it's equal to amount

descriptionstringrequired

The description of the item

taxobjectnullableshow 4 properties

currencystringrequired

Specifies the currency used, following the ISO 4217 standard for fiat currencies (e.g., CLP, ARS, MXN). Go to the currencies page for the complete list of supported values.

paymentMethodsAllowedstring[]min 1 itemsrequired

Allowed payment methods.

customerobject

Optional customer to pass into the checkout session

idstring

Unique identifier for the internal service.

firstNamestring

Payer's name

emailstring

Payer's email

lastNamestring

Payer's last name

phoneNumberstring

Payer's phone number without prefix

phoneNumberPrefixstring

Phone number prefix (e.g., +57)

documentTypestring

Documeny type of the entity (e.g., RUT, CURP, CURL). Go to the Supported Identity document types page for the complete list of supported values.

documentNumberstring

The document number associated with the documentType

addressobjectshow 8 properties

The entity’s address information.

destinationsobject[]min 1 itemsrequired

A list of destinations for the transaction.

namestring

The name of the source or destination of the transaction.

typestringrequired

ACCOUNT

externalIdstring

External reference identifier for integrations.

amountstringrequired

The amount involved in the transaction.

metadataobjectshow 3 properties

Additional metadata related to the transaction source or destination.

accountobjectrequiredshow 4 properties

durationinteger≥ 30required

Amount of seconds for payment link to be inactivated after creation

customerRequirementsstring[]

ownerobjectrequired

Identity reference object used inside account nodes.

identityIdstringrequired

User unique identifier

namestring

User name

lastnamestring

User lastname

nicknamestring

User nickname

documentNumberstring

User DNI

entityTypestring

Entity type of identity

successUrlstring

The URL to which the end user will be redirected after successful payment completion.

failedUrlstring

The URL to which the end user will be redirected after failed payment or cancellation.

Responses

201Resource created successfully.

idstringrequired

Unique identifier for the internal service.

paymentLinkIdstring

Reference Payment Link ID

checkoutTokenstring

Reference for checkout url

paymentConfigsobject[]requiredshow items

createdAtstringdate-timerequired

When the link expires

statusstringrequired

ATTEMPTACTIVEEXPIREDFINISHEDPROCESSING_PAYMENTFAILED

itemsobject[]requiredshow items

List of items to pay for

currencystringrequired

Specifies the currency used, following the ISO 4217 standard for fiat currencies (e.g., CLP, ARS, MXN). Go to the currencies page for the complete list of supported values.

preTaxAmountstringrequired

Addition of all items preTaxAmounts

totalAmountstringrequired

Addition of all items totalAmounts

urlstringrequired

Url to open checkout flow

paymentMethodsAllowedstring[]min 1 itemsrequired

Allowed payment methods.

customerobjectnullableshow 9 properties

Optional customer to pass into the checkout session

redirectUrlstring

The URL to which the end user will be redirected after completing the payment.

destinationsobject[]min 1 itemsrequiredshow items

A list of destinations for the transaction.

customerRequirementsstring[]

expiresAtstringdate-timerequired

ownerobjectrequiredshow 6 properties

Identity reference object used inside account nodes.

400Invalid request parameters or payload.

errorobjectshow 2 properties

messagestringnullable

Human-readable message. May be null.

500Unexpected internal server error.

errorobjectshow 2 properties

messagestringnullable

Human-readable message. May be null.

Request

HTTPcurlTypeScriptPythonGoRust

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

{
  "checkoutToken": "string",
  "items": [
    {
      "preTaxAmount": "string",
      "totalAmount": "string",
      "description": "string"
    }
  ],
  "currency": "string",
  "paymentMethodsAllowed": [
    "CARD"
  ],
  "customer": {},
  "destinations": [
    {
      "type": "ACCOUNT",
      "amount": "string",
      "account": {
        "type": null,
        "currency": null,
        "accountNumber": null,
        "accountHolder": null
      }
    }
  ],
  "duration": 30,
  "customerRequirements": [
    "firstName"
  ],
  "owner": {
    "identityId": "string"
  },
  "successUrl": "string"
}

curl -X POST \
  'https://api.conomyhq.com/sandbox/checkout-sessions' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {YOUR_API_KEY}' \
  -H 'conomyhq-api-version: 24-04-2025' \
  -H 'User-Agent: MyApp/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "checkoutToken": "string",
    "items": [
      {
        "preTaxAmount": "string",
        "totalAmount": "string",
        "description": "string"
      }
    ],
    "currency": "string",
    "paymentMethodsAllowed": [
      "CARD"
    ],
    "customer": {},
    "destinations": [
      {
        "type": "ACCOUNT",
        "amount": "string",
        "account": {
          "type": null,
          "currency": null,
          "accountNumber": null,
          "accountHolder": null
        }
      }
    ],
    "duration": 30,
    "customerRequirements": [
      "firstName"
    ],
    "owner": {
      "identityId": "string"
    },
    "successUrl": "string"
  }'

const response = await fetch('https://api.conomyhq.com/sandbox/checkout-sessions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'x-api-key': '{YOUR_API_KEY}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "checkoutToken": "string",
    "items": [
      {
        "preTaxAmount": "string",
        "totalAmount": "string",
        "description": "string"
      }
    ],
    "currency": "string",
    "paymentMethodsAllowed": [
      "CARD"
    ],
    "customer": {},
    "destinations": [
      {
        "type": "ACCOUNT",
        "amount": "string",
        "account": {
          "type": null,
          "currency": null,
          "accountNumber": null,
          "accountHolder": null
        }
      }
    ],
    "duration": 30,
    "customerRequirements": [
      "firstName"
    ],
    "owner": {
      "identityId": "string"
    },
    "successUrl": "string"
  }),
});

const data = await response.json();

import requests

payload = {
    "checkoutToken": "string",
    "items": [
        {
            "preTaxAmount": "string",
            "totalAmount": "string",
            "description": "string"
        }
    ],
    "currency": "string",
    "paymentMethodsAllowed": [
        "CARD"
    ],
    "customer": {},
    "destinations": [
        {
            "type": "ACCOUNT",
            "amount": "string",
            "account": {
                "type": null,
                "currency": null,
                "accountNumber": null,
                "accountHolder": null
            }
        }
    ],
    "duration": 30,
    "customerRequirements": [
        "firstName"
    ],
    "owner": {
        "identityId": "string"
    },
    "successUrl": "string"
}

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

data = response.json()

package main

import (
	"encoding/json"
	"net/http"
	"bytes"
)

func main() {
	payload, _ := json.Marshal(	{
	  "checkoutToken": "string",
	  "items": [
	    {
	      "preTaxAmount": "string",
	      "totalAmount": "string",
	      "description": "string"
	    }
	  ],
	  "currency": "string",
	  "paymentMethodsAllowed": [
	    "CARD"
	  ],
	  "customer": {},
	  "destinations": [
	    {
	      "type": "ACCOUNT",
	      "amount": "string",
	      "account": {
	        "type": null,
	        "currency": null,
	        "accountNumber": null,
	        "accountHolder": null
	      }
	    }
	  ],
	  "duration": 30,
	  "customerRequirements": [
	    "firstName"
	  ],
	  "owner": {
	    "identityId": "string"
	  },
	  "successUrl": "string"
	})
	body := bytes.NewBuffer(payload)
	req, _ := http.NewRequest("POST", "https://api.conomyhq.com/sandbox/checkout-sessions", body)
	req.Header.Set("Authorization", "Bearer {ACCESS_TOKEN}")
	req.Header.Set("x-api-key", "{YOUR_API_KEY}")
	req.Header.Set("conomyhq-api-version", "24-04-2025")
	req.Header.Set("User-Agent", "MyApp/1.0")
	req.Header.Set("Content-Type", "application/json")

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

	var data map[string]any
	json.NewDecoder(resp.Body).Decode(&data)
}

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let resp = client
        .post("https://api.conomyhq.com/sandbox/checkout-sessions")
        .header("Authorization", "Bearer {ACCESS_TOKEN}")
        .header("x-api-key", "{YOUR_API_KEY}")
        .header("conomyhq-api-version", "24-04-2025")
        .header("User-Agent", "MyApp/1.0")
        .header("Content-Type", "application/json")
        .json(&json!({
        "checkoutToken": "string",
        "items": [
                {
                        "preTaxAmount": "string",
                        "totalAmount": "string",
                        "description": "string"
                }
        ],
        "currency": "string",
        "paymentMethodsAllowed": [
                "CARD"
        ],
        "customer": {},
        "destinations": [
                {
                        "type": "ACCOUNT",
                        "amount": "string",
                        "account": {
                                "type": null,
                                "currency": null,
                                "accountNumber": null,
                                "accountHolder": null
                        }
                }
        ],
        "duration": 30,
        "customerRequirements": [
                "firstName"
        ],
        "owner": {
                "identityId": "string"
        },
        "successUrl": "string"
}))
        .send()
        .await?;

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

Response

201 400 401 403 404 422 500

{
  "id": "string",
  "paymentLinkId": "string",
  "checkoutToken": "string",
  "paymentConfigs": [
    {
      "currency": "string",
      "product": "string",
      "exchangeRate": "string",
      "paymentMethods": [
        null
      ]
    }
  ],
  "createdAt": "2024-01-15T10:30:00.000Z",
  "status": "ATTEMPT",
  "items": [
    {
      "preTaxAmount": "string",
      "totalAmount": "string",
      "description": "string"
    }
  ],
  "currency": "string",
  "preTaxAmount": "string",
  "totalAmount": "string"
}

{
  "error": {
    "type": "bad_request",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "unauthorized",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "forbidden",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "not_found",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "validation_error",
    "info": {
      "field": "string",
      "message": "string"
    }
  },
  "message": null
}

{
  "error": {
    "type": "internal_error",
    "info": null
  },
  "message": null
}