checkout session

Checkout sessions represent a temporary, tokenized context in which a payer completes a payment flow.

A session is created from a payment link or directly via the API, and it holds the state needed to process a payment — including the selected origins, destinations, and method. Sessions have a limited lifespan and can be refreshed using their associated token.

Use the Checkout Sessions API to create sessions, retrieve them, initiate payments within a session, or delete sessions that are no longer needed.

Endpoints

GET /checkout-sessions
GET /checkout-sessions/:checkout_session_id
DELETE /checkout-sessions/:checkout_session_id
POST /checkout-sessions
POST /checkout-sessions/:checkout_session_id/payments
POST /checkout-sessions/token/:checkout-token/refresh
POST /payment-links/token/:checkout-token/checkout-sessions

Get Checkout sessions

get

Lists checkout sessions with filtering and pagination options.

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

identityIdstringOptional

Owner Identity Id

Example: 1234a

accountNumberstringOptional

Destination Account Number

Example: 1234

statusstringOptional

Checkout session status

Example: ATTEMPT

startDatestringOptional

(dd/mm/yyyy) Start date filters created Date min

Example: 01/04/2025

endDatestringOptional

(dd/mm/yyyy) End date filters created Date max

Example: 08/04/2025

sortstringOptional

Sorts the results by param:asc | param:desc

Example: createdAt:desc

limitstringOptional

Specifies the maximum number of items to return in a single request.

Example: 50

offsetstringOptional

Skips the input value from the current view

Example: 0

Header parameters

conomyhq-api-versionstringOptional

v1: empty ; v2: 24-04-2025

Default: none, is the first API versionExample: 24-04-2025

x-api-keystringRequired

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

User-AgentstringRequired

Identifies the application making the request.

Responses

200

Request processed successfully.

application/json

400

Invalid request parameters or payload.

application/json

500

Unexpected internal server error.

application/json

get

/checkout-sessions

HTTPcURLJavaScriptPython

GET /checkout-sessions HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
x-api-key: text
User-Agent: text
Accept: */*

{
  "pagination": {
    "count": 1,
    "next": 1,
    "previous": 1,
    "total": 1
  },
  "results": [
    {
      "id": "text",
      "paymentLinkId": "text",
      "checkoutToken": "text",
      "paymentConfigs": [
        {
          "currency": "text",
          "product": "text",
          "exchangeRate": "text",
          "paymentMethods": [
            {
              "id": "text",
              "type": "text",
              "enabled": true,
              "requiredFields": [
                "text"
              ],
              "purchaseAmount": "text"
            }
          ]
        }
      ],
      "createdAt": "2026-03-19T20:12:03.091Z",
      "status": "ATTEMPT",
      "items": [
        {
          "preTaxAmount": "text",
          "totalAmount": "text",
          "description": "text",
          "tax": {
            "name": "text",
            "type": "FIXED",
            "value": "text",
            "amount": "text"
          }
        }
      ],
      "currency": "text",
      "preTaxAmount": "text",
      "totalAmount": "text",
      "url": "text",
      "paymentMethodsAllowed": [
        "CARD"
      ],
      "customer": {
        "id": "text",
        "firstName": "text",
        "email": "text",
        "lastName": "text",
        "phoneNumber": "text",
        "phoneNumberPrefix": "text",
        "documentType": "text",
        "documentNumber": "text",
        "address": {
          "administrativeAreaLevel1": "text",
          "administrativeAreaLevel2": "text",
          "administrativeAreaLevel3": "text",
          "street": "text",
          "streetNumber": "text",
          "optionalAddress": "text",
          "country": "text",
          "zipcode": "text"
        }
      },
      "redirectUrl": "text",
      "destinations": [
        {
          "name": "text",
          "type": "ACCOUNT",
          "externalId": "text",
          "amount": "text",
          "metadata": {
            "image": "text",
            "description": "text",
            "category": "text"
          },
          "account": {
            "type": "CHECKING",
            "currency": "text",
            "accountNumber": "text",
            "accountHolder": "text"
          }
        }
      ],
      "customerRequirements": [
        "firstName"
      ],
      "expiresAt": "2026-03-19T20:12:03.091Z",
      "owner": {
        "identityId": "text",
        "name": "text",
        "lastname": "text",
        "nickname": "text",
        "documentNumber": "text",
        "entityType": "text"
      }
    }
  ]
}

Get checkout session

get

Retrieves a checkout session by ID.

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

checkout_session_idstringRequired

Unique identifier of the checkout session.

Header parameters

x-api-keystringRequired

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

User-AgentstringRequired

Identifies the application making the request.

Responses

200

Request processed successfully.

application/json

idstringRequired

Unique identifier for the internal service.

paymentLinkIdstringOptional

Reference Payment Link ID

checkoutTokenstringOptional

Reference for checkout url

createdAtstring · date-timeRequired

When the link expires

statusstring · enumRequired

Whether the payment link’s url is active. If false, customers visiting the URL will be shown a page saying that the link has been deactivated

Possible values:

currencystringRequired

Currency for payment

preTaxAmountstringRequired

Addition of all items preTaxAmounts

totalAmountstringRequired

Addition of all items totalAmounts

urlstringRequired

Url to open checkout flow

redirectUrlstringOptional

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

expiresAtstring · date-timeRequired

400

Invalid request parameters or payload.

application/json

500

Unexpected internal server error.

application/json

get

/checkout-sessions/{checkout_session_id}

HTTPcURLJavaScriptPython

GET /checkout-sessions/{checkout_session_id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
x-api-key: text
User-Agent: text
Accept: */*

{
  "id": "text",
  "paymentLinkId": "text",
  "checkoutToken": "text",
  "paymentConfigs": [
    {
      "currency": "text",
      "product": "text",
      "exchangeRate": "text",
      "paymentMethods": [
        {
          "id": "text",
          "type": "text",
          "enabled": true,
          "requiredFields": [
            "text"
          ],
          "purchaseAmount": "text"
        }
      ]
    }
  ],
  "createdAt": "2026-03-19T20:12:03.091Z",
  "status": "ATTEMPT",
  "items": [
    {
      "preTaxAmount": "text",
      "totalAmount": "text",
      "description": "text",
      "tax": {
        "name": "text",
        "type": "FIXED",
        "value": "text",
        "amount": "text"
      }
    }
  ],
  "currency": "text",
  "preTaxAmount": "text",
  "totalAmount": "text",
  "url": "text",
  "paymentMethodsAllowed": [
    "CARD"
  ],
  "customer": {
    "id": "text",
    "firstName": "text",
    "email": "text",
    "lastName": "text",
    "phoneNumber": "text",
    "phoneNumberPrefix": "text",
    "documentType": "text",
    "documentNumber": "text",
    "address": {
      "administrativeAreaLevel1": "text",
      "administrativeAreaLevel2": "text",
      "administrativeAreaLevel3": "text",
      "street": "text",
      "streetNumber": "text",
      "optionalAddress": "text",
      "country": "text",
      "zipcode": "text"
    }
  },
  "redirectUrl": "text",
  "destinations": [
    {
      "name": "text",
      "type": "ACCOUNT",
      "externalId": "text",
      "amount": "text",
      "metadata": {
        "image": "text",
        "description": "text",
        "category": "text"
      },
      "account": {
        "type": "CHECKING",
        "currency": "text",
        "accountNumber": "text",
        "accountHolder": "text"
      }
    }
  ],
  "customerRequirements": [
    "firstName"
  ],
  "expiresAt": "2026-03-19T20:12:03.091Z",
  "owner": {
    "identityId": "text",
    "name": "text",
    "lastname": "text",
    "nickname": "text",
    "documentNumber": "text",
    "entityType": "text"
  }
}

Delete checkout session

delete

Deletes (invalidates) a checkout session.

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

checkout_session_idstringRequired

Unique identifier of the checkout session to delete.

Header parameters

x-api-keystringRequired

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

User-AgentstringRequired

Identifies the application making the request.

Responses

200

Request processed successfully.

application/json

objectOptional

400

Invalid request parameters or payload.

application/json

500

Unexpected internal server error.

application/json

delete

/checkout-sessions/{checkout_session_id}

HTTPcURLJavaScriptPython

DELETE /checkout-sessions/{checkout_session_id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
x-api-key: text
User-Agent: text
Accept: */*

{}

Refresh checkout session

post

Refreshes a checkout session token and returns updated session data.

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

checkout-tokenstringRequired

Checkout token of the session to refresh.

Header parameters

x-api-keystringRequired

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

User-AgentstringRequired

Identifies the application making the request.

Body

application/json

objectOptional

Responses

201

Resource created successfully.

application/json

400

Invalid request parameters or payload.

application/json

500

Unexpected internal server error.

application/json

post

/checkout-sessions/token/{checkout-token}/refresh

HTTPcURLJavaScriptPython

POST /checkout-sessions/token/{checkout-token}/refresh HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
x-api-key: text
User-Agent: text
Content-Type: application/json
Accept: */*
Content-Length: 2

{}

{
  "id": "text",
  "paymentLinkId": "text",
  "checkoutToken": "text",
  "paymentConfigs": [
    {
      "currency": "text",
      "product": "text",
      "exchangeRate": "text",
      "paymentMethods": [
        {
          "id": "text",
          "type": "text",
          "enabled": true,
          "requiredFields": [
            "text"
          ],
          "purchaseAmount": "text"
        }
      ]
    }
  ],
  "createdAt": "2026-03-19T20:12:03.091Z",
  "status": "ATTEMPT",
  "items": [
    {
      "preTaxAmount": "text",
      "totalAmount": "text",
      "description": "text",
      "tax": {
        "name": "text",
        "type": "FIXED",
        "value": "text",
        "amount": "text"
      }
    }
  ],
  "currency": "text",
  "preTaxAmount": "text",
  "totalAmount": "text",
  "url": "text",
  "paymentMethodsAllowed": [
    "CARD"
  ],
  "customer": {
    "id": "text",
    "firstName": "text",
    "email": "text",
    "lastName": "text",
    "phoneNumber": "text",
    "phoneNumberPrefix": "text",
    "documentType": "text",
    "documentNumber": "text",
    "address": {
      "administrativeAreaLevel1": "text",
      "administrativeAreaLevel2": "text",
      "administrativeAreaLevel3": "text",
      "street": "text",
      "streetNumber": "text",
      "optionalAddress": "text",
      "country": "text",
      "zipcode": "text"
    }
  },
  "redirectUrl": "text",
  "destinations": [
    {
      "name": "text",
      "type": "ACCOUNT",
      "externalId": "text",
      "amount": "text",
      "metadata": {
        "image": "text",
        "description": "text",
        "category": "text"
      },
      "account": {
        "type": "CHECKING",
        "currency": "text",
        "accountNumber": "text",
        "accountHolder": "text"
      }
    }
  ],
  "customerRequirements": [
    "firstName"
  ],
  "expiresAt": "2026-03-19T20:12:03.091Z",
  "owner": {
    "identityId": "text",
    "name": "text",
    "lastname": "text",
    "nickname": "text",
    "documentNumber": "text",
    "entityType": "text"
  }
}

Create checkout session

post

Creates a checkout session for a payment link.

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

x-api-keystringRequired

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

User-AgentstringRequired

Identifies the application making the request.

Body

application/json

Request payload used to create a checkout session.

checkoutTokenstringRequired

Reference for checkout url

currencystringRequired

Currency for payment

durationinteger · min: 30Required

Amount of seconds for payment link to be inactivated after creation

successUrlstringOptional

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

failedUrlstringOptional

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

Responses

201

Resource created successfully.

application/json

400

Invalid request parameters or payload.

application/json

500

Unexpected internal server error.

application/json

post

/checkout-sessions

HTTPcURLJavaScriptPython

POST /checkout-sessions HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
x-api-key: text
User-Agent: text
Content-Type: application/json
Accept: */*
Content-Length: 1061

{
  "checkoutToken": "text",
  "items": [
    {
      "preTaxAmount": "text",
      "totalAmount": "text",
      "description": "text",
      "tax": {
        "name": "text",
        "type": "FIXED",
        "value": "text",
        "amount": "text"
      }
    }
  ],
  "currency": "text",
  "paymentMethodsAllowed": [
    "CARD"
  ],
  "customer": {
    "id": "text",
    "firstName": "text",
    "email": "text",
    "lastName": "text",
    "phoneNumber": "text",
    "phoneNumberPrefix": "text",
    "documentType": "text",
    "documentNumber": "text",
    "address": {
      "administrativeAreaLevel1": "text",
      "administrativeAreaLevel2": "text",
      "administrativeAreaLevel3": "text",
      "street": "text",
      "streetNumber": "text",
      "optionalAddress": "text",
      "country": "text",
      "zipcode": "text"
    }
  },
  "destinations": [
    {
      "name": "text",
      "type": "ACCOUNT",
      "externalId": "text",
      "amount": "text",
      "metadata": {
        "image": "text",
        "description": "text",
        "category": "text"
      },
      "account": {
        "type": "CHECKING",
        "currency": "text",
        "accountNumber": "text",
        "accountHolder": "text"
      }
    }
  ],
  "duration": 1,
  "customerRequirements": [
    "firstName"
  ],
  "owner": {
    "identityId": "text",
    "name": "text",
    "lastname": "text",
    "nickname": "text",
    "documentNumber": "text",
    "entityType": "text"
  },
  "successUrl": "text",
  "failedUrl": "text"
}

{
  "id": "text",
  "paymentLinkId": "text",
  "checkoutToken": "text",
  "paymentConfigs": [
    {
      "currency": "text",
      "product": "text",
      "exchangeRate": "text",
      "paymentMethods": [
        {
          "id": "text",
          "type": "text",
          "enabled": true,
          "requiredFields": [
            "text"
          ],
          "purchaseAmount": "text"
        }
      ]
    }
  ],
  "createdAt": "2026-03-19T20:12:03.091Z",
  "status": "ATTEMPT",
  "items": [
    {
      "preTaxAmount": "text",
      "totalAmount": "text",
      "description": "text",
      "tax": {
        "name": "text",
        "type": "FIXED",
        "value": "text",
        "amount": "text"
      }
    }
  ],
  "currency": "text",
  "preTaxAmount": "text",
  "totalAmount": "text",
  "url": "text",
  "paymentMethodsAllowed": [
    "CARD"
  ],
  "customer": {
    "id": "text",
    "firstName": "text",
    "email": "text",
    "lastName": "text",
    "phoneNumber": "text",
    "phoneNumberPrefix": "text",
    "documentType": "text",
    "documentNumber": "text",
    "address": {
      "administrativeAreaLevel1": "text",
      "administrativeAreaLevel2": "text",
      "administrativeAreaLevel3": "text",
      "street": "text",
      "streetNumber": "text",
      "optionalAddress": "text",
      "country": "text",
      "zipcode": "text"
    }
  },
  "redirectUrl": "text",
  "destinations": [
    {
      "name": "text",
      "type": "ACCOUNT",
      "externalId": "text",
      "amount": "text",
      "metadata": {
        "image": "text",
        "description": "text",
        "category": "text"
      },
      "account": {
        "type": "CHECKING",
        "currency": "text",
        "accountNumber": "text",
        "accountHolder": "text"
      }
    }
  ],
  "customerRequirements": [
    "firstName"
  ],
  "expiresAt": "2026-03-19T20:12:03.091Z",
  "owner": {
    "identityId": "text",
    "name": "text",
    "lastname": "text",
    "nickname": "text",
    "documentNumber": "text",
    "entityType": "text"
  }
}

Create Payment from checkout session

post

When creating a transaction from a checkout session, this endpoint provides a payment method and a provider system to process the payment.

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

checkout_session_idstringRequired

Unique identifier of the checkout session where the payment is submitted.

Header parameters

x-api-keystringRequired

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

User-AgentstringRequired

Identifies the application making the request.

Body

application/json

Request payload to submit a payment in an active checkout session.

descriptionstringOptional

A brief description of the transaction.

Responses

200

Request processed successfully.

application/json

Schema representing a financial transaction, including details about the transaction's origins, destinations, amounts, fees, and status.

idstringRequired

Unique identifier for the internal service.

externalIdstringRequired

External reference identifier for integrations.

identityIdstringRequired

Identifier linking the transaction to a specific user or organization.

identityExternalIdstringOptional

External reference identifier for the identity associated with the transaction.

accountNumberstringRequired

The account number involved in the transaction.

totalAmountstringRequired

The total amount of the transaction.

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.

descriptionstringOptional

A brief description of the transaction.

productstringOptional

The product or service related to the transaction. purchaseCurrency:Currency

statusstringRequired

The current status of the transaction (e.g., PENDING, AUTHORIZED, CAPTURED, ATTEMPT, REFUNDED).

typestring · enumRequired

Indicates the purpose of the payment. This field defines how the payment should be processed within the system, based on its intent—such as funding an account, withdrawing funds, transferring between users, collecting funds, or applying fees. Go to the payment types page for the complete list of supported values.

Possible values:

purchaseAmountstringOptional

The amount paid in the transaction.

purchaseCurrencystringOptional

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.

createdAtstringRequired

Timestamp indicating when the transaction was created.

updatedAtstringRequired

Timestamp indicating the last update to the transaction.

expiresAtstringOptional

Timestamp indicating when the transaction expires, if applicable.

capturedAtstringOptional

Timestamp indicating when the transaction was captured.

authorizedAtstringOptional

Timestamp indicating when the transaction was authorized.

refundedAtstringOptional

Timestamp indicating when the transaction was refunded, if applicable.

settlementstringOptional

Settlement period for the transaction.

400

Invalid request parameters or payload.

application/json

500

Unexpected internal server error.

application/json

post

/checkout-sessions/{checkout_session_id}/payments

HTTPcURLJavaScriptPython

POST /checkout-sessions/{checkout_session_id}/payments HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
x-api-key: text
User-Agent: text
Content-Type: application/json
Accept: */*
Content-Length: 166

{
  "origins": [
    {
      "name": "ETPAY",
      "type": "PAYMENT_INITATION",
      "amount": "100",
      "currency": "ARS",
      "paymentInitiation": {
        "origin": "ETPAY",
        "referenceId": "external_payment_id_1"
      }
    }
  ]
}

{
  "id": "text",
  "externalId": "text",
  "identityId": "text",
  "identityExternalId": "text",
  "accountNumber": "text",
  "totalAmount": "text",
  "currency": "text",
  "description": "text",
  "product": "text",
  "status": "text",
  "type": "PURCHASE",
  "purchaseAmount": "text",
  "purchaseCurrency": "text",
  "fees": [
    {
      "name": "text",
      "type": "FIXED",
      "value": "text",
      "amount": "text",
      "currency": "text"
    }
  ],
  "createdAt": "text",
  "updatedAt": "text",
  "expiresAt": "text",
  "capturedAt": "text",
  "authorizedAt": "text",
  "refundedAt": "text",
  "origins": [
    {
      "externalId": "text",
      "name": "text",
      "type": "CARD",
      "amount": "text",
      "currency": "text",
      "settlement": "text",
      "fee": {
        "name": "text",
        "type": "FIXED",
        "value": "text",
        "amount": "text",
        "currency": "text"
      },
      "identity": {},
      "metadata": {
        "image": "text",
        "description": "text",
        "category": "text"
      },
      "amountOut": "text",
      "card": {
        "holder": "text",
        "scheme": "text",
        "type": "text",
        "mask": "text",
        "country": "text",
        "token": "text"
      }
    }
  ],
  "destinations": [
    {
      "externalId": "text",
      "name": "text",
      "type": "CARD",
      "amount": "text",
      "currency": "text",
      "settlement": "text",
      "fee": {
        "name": "text",
        "type": "FIXED",
        "value": "text",
        "amount": "text",
        "currency": "text"
      },
      "identity": {},
      "metadata": {
        "image": "text",
        "description": "text",
        "category": "text"
      },
      "amountOut": "text",
      "card": {
        "holder": "text",
        "scheme": "text",
        "type": "text",
        "mask": "text",
        "country": "text",
        "token": "text"
      }
    }
  ],
  "settlement": "text"
}

Create checkout session from payment-link

post

Creates a checkout session from a payment-link checkout token.

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

checkout-tokenstringRequired

Checkout token that identifies the payment link session context.

Header parameters

x-api-keystringRequired

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

User-AgentstringRequired

Identifies the application making the request.

Body

application/json

objectOptional

Responses

201

Resource created successfully.

application/json

400

Invalid request parameters or payload.

application/json

500

Unexpected internal server error.

application/json

post

/payment-links/token/{checkout-token}/checkout-sessions

HTTPcURLJavaScriptPython

POST /payment-links/token/{checkout-token}/checkout-sessions HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
x-api-key: text
User-Agent: text
Content-Type: application/json
Accept: */*
Content-Length: 2

{}

{
  "id": "text",
  "paymentLinkId": "text",
  "checkoutToken": "text",
  "paymentConfigs": [
    {
      "currency": "text",
      "product": "text",
      "exchangeRate": "text",
      "paymentMethods": [
        {
          "id": "text",
          "type": "text",
          "enabled": true,
          "requiredFields": [
            "text"
          ],
          "purchaseAmount": "text"
        }
      ]
    }
  ],
  "createdAt": "2026-03-19T20:12:03.091Z",
  "status": "ATTEMPT",
  "items": [
    {
      "preTaxAmount": "text",
      "totalAmount": "text",
      "description": "text",
      "tax": {
        "name": "text",
        "type": "FIXED",
        "value": "text",
        "amount": "text"
      }
    }
  ],
  "currency": "text",
  "preTaxAmount": "text",
  "totalAmount": "text",
  "url": "text",
  "paymentMethodsAllowed": [
    "CARD"
  ],
  "customer": {
    "id": "text",
    "firstName": "text",
    "email": "text",
    "lastName": "text",
    "phoneNumber": "text",
    "phoneNumberPrefix": "text",
    "documentType": "text",
    "documentNumber": "text",
    "address": {
      "administrativeAreaLevel1": "text",
      "administrativeAreaLevel2": "text",
      "administrativeAreaLevel3": "text",
      "street": "text",
      "streetNumber": "text",
      "optionalAddress": "text",
      "country": "text",
      "zipcode": "text"
    }
  },
  "redirectUrl": "text",
  "destinations": [
    {
      "name": "text",
      "type": "ACCOUNT",
      "externalId": "text",
      "amount": "text",
      "metadata": {
        "image": "text",
        "description": "text",
        "category": "text"
      },
      "account": {
        "type": "CHECKING",
        "currency": "text",
        "accountNumber": "text",
        "accountHolder": "text"
      }
    }
  ],
  "customerRequirements": [
    "firstName"
  ],
  "expiresAt": "2026-03-19T20:12:03.091Z",
  "owner": {
    "identityId": "text",
    "name": "text",
    "lastname": "text",
    "nickname": "text",
    "documentNumber": "text",
    "entityType": "text"
  }
}