Create Cart

This endpoint creates a new cart containing a single product for a given terminal. It is the first step in the checkout process after product selection in a location-based flow.

🔍 Description

Use this method to:

Initialize a cart with one product

Submit all required purchase and delivery details

Receive cart metadata including pricing and expiration

📌 Currently, this method supports only one product per cart. Multi-product carts are not yet supported.

📥 Request Details

Method: POST

Authentication: Required

Path Parameters:

terminalId (integer): ID of the requesting terminal

productId (integer): ID of the selected product

Body Parameters:

Field	Type	Description
`productId`	integer	ID of the product being added to the cart
`countryId`	integer	ID of the selected country
`stateId`	integer	ID of the selected state or province
`locationId`	integer	ID of the delivery location
`municipalityId`	integer	ID of the selected municipality
`buyerName`	string	Name of the buyer
`buyerSurname`	string	Surname of the buyer
`buyerPhone`	string	Phone number of the buyer
`buyerEmail`	string	Email address of the buyer
`buyerDocumentNumber`	string	Document number of the buyer
`beneficiaryName`	string	Name of the beneficiary
`beneficiarySurname`	string	Surname of the beneficiary
`beneficiaryPhone`	string	Phone number of the beneficiary
`beneficiaryEmail`	string	Email address of the beneficiary
`beneficiaryDocumentNumber`	string	Document number of the beneficiary
`beneficiaryDocumentType`	string	Type of document (e.g., `PASSPORT`, `ID_CARD`)
`city`	string	City of delivery
`address`	string	Full delivery address

Example Request

{
  "productId": 501,
  "countryId": 34,
  "stateId": 201,
  "locationId": 401,
  "municipalityId": 301,
  "buyerName": "Carlota",
  "buyerSurname": "Gómez",
  "buyerPhone": "+34000000000",
  "buyerEmail": "cg@example.com",
  "buyerDocumentNumber": "X1234567",
  "beneficiaryName": "Luis",
  "beneficiarySurname": "Gómez",
  "beneficiaryPhone": "+34000000001",
  "beneficiaryEmail": "luis@example.com",
  "beneficiaryDocumentNumber": "Y7654321",
  "city": "Madrid",
  "address": "Calle Mayor 1, 1ºB",
  "beneficiaryDocumentType": "PASSPORT"
}

📤 Response

Returns cart creation confirmation and pricing details:

Field	Type	Description
`resultMessage`	string	Human-readable message describing the result of the operation
`resultCode`	integer	Internal result code (e.g., 0 for success)
`cartId`	integer	Unique identifier of the newly created cart
`productPriceX100`	integer	Base price of the product, expressed in cents
`amountToSendX100`	integer	Amount intended to be sent, expressed in cents
`deliveryPriceX100`	integer	Cost of delivery, expressed in cents

Example Response

{
  "resultMessage": "Cart created successfully",
  "resultCode": 0,
  "cartId": 874231,
  "productPriceX100": 1300,
  "amountToSendX100": 1500,
  "deliveryPriceX100": 200
}

🧠 Usage Notes

This method must be called before initiating payment.

The cart expires after a short time window (validUntil), so payment should follow promptly.

The cartId returned is required for the next step: executing payment.

Request

Path Params

terminalId

integer <int32>

required

operatorId

integer <int32>

required

Header Params

string

required

Default:

string

required

Default:

string

required

Default:

Body Params application/json

productId

integer <int64>

required

countryId

integer <int32>

required

stateId

integer <int32>

optional

if required in the dynamic flow.

locationId

integer <int32>

optional

if required in the dynamic flow.

municipalityId

integer <int32>

optional

if required in the dynamic flow.

buyerName

string

required

buyerSurname

string

required

buyerPhone

string

required

buyerEmail

string

required

buyerDocumentNumber

string

required

beneficiaryName

string

required

beneficiarySurname

string

required

beneficiaryPhone

string

required

beneficiaryEmail

string

required

beneficiaryDocumentNumber

string

required

city

string

optional

Required only if the product is of type “delivery” and the “Get Deliver Locations” step has been completed.

address

string

optional

Required only if the product is of type “delivery” and the “Get Deliver Locations” step has been completed.

beneficiaryDocumentType

enum<string>

required

Allowed values:

PASSPORTID_CARD

Example

{
    "productId": 0,
    "countryId": 0,
    "stateId": 0,
    "locationId": 0,
    "municipalityId": 0,
    "buyerName": "string",
    "buyerSurname": "string",
    "buyerPhone": "string",
    "buyerEmail": "string",
    "buyerDocumentNumber": "string",
    "beneficiaryName": "string",
    "beneficiarySurname": "string",
    "beneficiaryPhone": "string",
    "beneficiaryEmail": "string",
    "beneficiaryDocumentNumber": "string",
    "city": "string",
    "address": "string",
    "beneficiaryDocumentType": "PASSPORT"
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200OK

application/json

Body

resultMessage

string

required

resultCode

integer

required

cartId

integer

required

productPriceX100

integer

required

amountToSendX100

integer

required

deliveryPriceX100

integer

required

Example

{
    "resultMessage": "string",
    "resultCode": 0,
    "cartId": 0,
    "productPriceX100": 0,
    "amountToSendX100": 0,
    "deliveryPriceX100": 0
}

🔍 Description#

📥 Request Details#

Example Request#

📤 Response#

Example Response#

🧠 Usage Notes#

Request

Request samples

Responses

🔍 Description

📥 Request Details

Example Request

📤 Response

Example Response

🧠 Usage Notes