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.

application/json

Body

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 Code Samples

Responses

Create Cart

🔍 Description#

📥 Request Details#

Example Request#

📤 Response#

Example Response#

🧠 Usage Notes#

Request

Request Code Samples

Responses

🔍 Description

📥 Request Details

Example Request

📤 Response

Example Response

🧠 Usage Notes