Checkout and MercadoPago Payment Endpoints

The API supports two checkout flows: a direct flow for bank transfers, voucher uploads, or cash-on-delivery payments, and a MercadoPago flow for card and online payments. Both flows require a valid Bearer token, read the authenticated user’s current cart, create a Sale record with SaleDetail rows, decrement product stock, clear the cart, and send a confirmation email.

The MercadoPago flow requires two environment variables to be configured on the server:

MERCADOPAGO_KEY — your MercadoPago access token (obtained from the MercadoPago developer dashboard).
URL_TIENDA — the base URL of your storefront, including a trailing slash (e.g. https://mystore.com/). Used to build the back_urls redirect targets after payment.

Direct Checkout Flow

Use this flow when the customer pays by bank transfer, uploads a payment voucher, or uses any non-MercadoPago payment method.

(Optional) Save checkout data temporarily

Before the customer finalises the order, you can persist the delivery address and order notes server-side. This is especially useful for multi-step checkout forms where the user may navigate away.POST /api/ecommerce/checkout-temp

curl --request POST \
  --url https://your-domain.com/api/ecommerce/checkout-temp \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "description": "Please deliver in the afternoon.",
    "sale_address": {
      "name": "María",
      "surname": "García",
      "phone": "+573001234567",
      "address": "Calle 123 # 45-67",
      "city": "Bogotá",
      "country_region": "Colombia",
      "street": "Avenida Principal",
      "postcode_zip": "110111",
      "email": "maria@example.com",
      "company": ""
    }
  }'

The server upserts a SaleTemp record for the authenticated user (one record per user). The sale_address object is JSON-encoded and stored in the SaleTemp.sale_address column.Response:

{ "message": 200 }

Place the order

Submits the order. The server reads the authenticated user’s cart, creates the sale record, and processes all cart items.POST /api/ecommerce/checkout

curl --request POST \
  --url https://your-domain.com/api/ecommerce/checkout \
  --header "Authorization: Bearer <token>" \
  --form "total=599800" \
  --form "subtotal=599800" \
  --form "description=Please deliver in the afternoon." \
  --form "method_payment=bank_transfer" \
  --form "n_transaccion=REF-20240610-001" \
  --form "sale_address[name]=María" \
  --form "sale_address[surname]=García" \
  --form "sale_address[phone]=+573001234567" \
  --form "sale_address[address]=Calle 123 # 45-67" \
  --form "sale_address[city]=Bogotá" \
  --form "sale_address[country_region]=Colombia" \
  --form "sale_address[street]=Avenida Principal" \
  --form "sale_address[postcode_zip]=110111" \
  --form "sale_address[email]=maria@example.com" \
  --form "file_imagen=@/path/to/voucher.jpg"

This endpoint accepts multipart/form-data when uploading a voucher image. Use application/json when file_imagen is not included.

Body parameters

total

number

required

Grand total of the order in the selected currency.

subtotal

number

required

Order subtotal before any additional fees.

description

string

Optional delivery notes or order comments.

method_payment

string

required

Payment method identifier, e.g. "bank_transfer", "cash", "voucher".

n_transaccion

string

Optional external transaction or reference number supplied by the customer.

file_imagen

file (multipart)

Optional payment voucher image (JPG, PNG, etc.). Stored in OCI Object Storage under juandevops/ecommerce/public/comprobantes/.

sale_address

object

required

Delivery address. See sale_address fields below.

Server processes the order

After receiving the request the server performs these actions:

Creates a Sale record with user_id, total, subtotal, description, method_payment, n_transaccion.
If file_imagen was uploaded, stores the file in OCI Object Storage and updates sale.comprobante.
For each cart item, creates a SaleDetail record cloned from the cart item.
Decrements stock:
- If product_variation_id is set: decrements the variation’s stock (and its parent variation’s stock if it is a sub-variation).
- Otherwise: decrements the base product’s stock.
Deletes the cart item.
Creates a SaleAddres record from the sale_address payload.
Calls Cache::flush() to invalidate all cached product and storefront data.
Sends a SaleMail confirmation email to the authenticated user’s email address.

Receive confirmation

{ "message": 200 }

MercadoPago Flow

Use this flow when the customer pays online via MercadoPago (credit/debit card, PSE, etc.).

Save checkout data temporarily

Persist the delivery address before redirecting to MercadoPago.POST /api/ecommerce/checkout-temp — same as Step 1 of the direct flow above.

Create a MercadoPago preference

The server reads the authenticated user’s cart, maps each item to a MercadoPago preference item, and creates a preference via the MercadoPago Preferences API.GET /api/ecommerce/mercadopago

curl --request GET \
  --url https://your-domain.com/api/ecommerce/mercadopago \
  --header "Authorization: Bearer <token>"

The preference is created with:

items — each cart item mapped to { title, quantity, currency_id, unit_price }. unit_price is round(subtotal).
back_urls.success → {URL_TIENDA}mercado-pago-success
back_urls.failure → {URL_TIENDA}mercado-pago-failure
back_urls.pending → {URL_TIENDA}mercado-pago-pending
redirect_urls — same paths as back_urls.
auto_return: "approved" — MercadoPago auto-redirects on success.
external_reference — a unique ID generated with uniqid().

Response:

{
  "preference": {
    "id": "123456789-abcd-efgh-ijkl-mnopqrstuvwx",
    "init_point": "https://www.mercadopago.com.co/checkout/v1/redirect?pref_id=...",
    "sandbox_init_point": "https://sandbox.mercadopago.com.co/checkout/v1/redirect?pref_id=...",
    "back_urls": {
      "success": "https://mystore.com/mercado-pago-success",
      "failure": "https://mystore.com/mercado-pago-failure",
      "pending": "https://mystore.com/mercado-pago-pending"
    }
  }
}

If the cart is empty, the server returns { "message": "El carrito está vacío" } with status 200.

Redirect the customer to MercadoPago

Use preference.init_point (production) or preference.sandbox_init_point (testing) to redirect the customer to the MercadoPago-hosted payment page. The customer completes payment on MercadoPago’s platform.

MercadoPago redirects back to your storefront

After a successful payment MercadoPago redirects to:

{URL_TIENDA}mercado-pago-success?payment_id=<PAYMENT_ID>&status=approved&...

Your frontend must extract the payment_id query parameter from this URL.

Confirm the order

Call this endpoint from your frontend with the payment_id received from MercadoPago’s redirect.POST /api/ecommerce/checkout-mercadopago

curl --request POST \
  --url https://your-domain.com/api/ecommerce/checkout-mercadopago \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "n_transaccion": "12345678901"
  }'

n_transaccion

string

required

The MercadoPago payment_id returned in the redirect URL query string.

The server:

Fetches payment details from https://api.mercadopago.com/v1/payments/{n_transaccion} using MERCADOPAGO_KEY.
Reads transaction_amount from the MercadoPago response and sets it as both total and subtotal on the sale.
Reads the SaleTemp record for the user and uses its description and sale_address (decoded from JSON).
Creates Sale, SaleDetail rows, decrements stock, clears cart, creates SaleAddres, flushes cache, and sends the confirmation email — identical to the direct checkout flow.

Response:

{ "message": 200 }

sale_address Fields

The sale_address object is required for both checkout flows and maps directly to the UserAddres model fields. It is persisted in the SaleAddres table linked to the created sale.

name

string

required

Recipient’s first name.

surname

string

required

Recipient’s last name.

phone

string

required

Contact phone number, e.g. "+573001234567".

address

string

required

Street address, e.g. "Calle 123 # 45-67".

street

string

Additional street / apartment line, e.g. "Avenida Principal".

city

string

required

City of delivery, e.g. "Bogotá".

country_region

string

required

Country or region of delivery, e.g. "Colombia".

postcode_zip

string

Postal / ZIP code, e.g. "110111".

string

Recipient email address for delivery notifications.

company

string

Optional company name.

Post-Checkout Side Effects

Regardless of which checkout flow is used, the server always performs these side effects upon successful order creation:

Cache flush — Cache::flush() is called, invalidating all cached storefront responses including the home feed and all product detail pages.
Confirmation email — a SaleMail email is dispatched to the authenticated user’s registered email address containing the order summary.

Authentication

Storefront

Admin

Checkout and MercadoPago Payment Endpoints

Direct Checkout Flow

Body parameters

MercadoPago Flow

sale_address Fields

Post-Checkout Side Effects

Build docs developers (and LLMs) love

Authentication

Storefront

Admin

Documentation Index

​Direct Checkout Flow

​Body parameters

​MercadoPago Flow

​sale_address Fields

​Post-Checkout Side Effects

Build docs developers (and LLMs) love

Direct Checkout Flow

Body parameters

MercadoPago Flow

sale_address Fields

Post-Checkout Side Effects