Cart checkout (payment)

Description

This service finalizes the checkout process by generating the necessary orders and creating a single, associated payment record in a "New" state. This provides all the information needed before redirecting a user to an external payment page.

The request can include optional fields for separate billing and shipping details, contact information, extra payment amounts, referral codes for promotions, and payment platform specifics (e.g., for "Cash on Delivery").

---

Request

Restrictions

• This service requires an authenticated user.

• Delivery information (addressCode or exchangeCenterId) is only required if the cart contains physical items.

Endpoint

PUT https://<server-url>/api/v4/mileage/{activity_code}/cart/payment

Path Parameters

Parameter	Type	Description
activity_code	String	The unique code for the mileage activity.

Parameters

Parameter	Location	Description
touchpoint	Query / Header	The identifier for the touchpoint. Use Thalamus-Touchpoint for the header.
token	Query / Header	The authentication token for the API session. Use Thalamus-Token for the header.

Full URL Example

https://<server-url>/api/v4/mileage/outdoors/cart/payment?touchpoint=test&token=...

Request Body

The request body contains order details, delivery instructions, payment information, and the list of items being checked out.

Top-Level Fields

Field	Type	Description
status	String	The desired status, typically "CHECKOUT_PAYMENT_PROCESSING".
addressCode	String	Delivery Option 1. The code for the consumer's shipping address.
exchangeCenterId	Integer	Delivery Option 2. The ID of the exchange center for pickup.
physicalLocationId	Integer	Delivery Option 3. The ID of a physical location for delivery.
principal	String	Delivery Option 4. The principal of a physical location, formatted as profileField|principalValue (e.g., fiscalId|72857877536).
billingAddressCode	String	Optional. The code for the billing address, if different from the shipping address.
firstName	String	Optional. The first name for the shipping contact.
lastName	String	Optional. The last name for the shipping contact.
contactNumber	String	Optional. The phone number for the shipping contact.
referringPrincipal	String	Optional. A referral code to apply a promotion.
extraPayment	Number	Optional. An additional monetary amount to be included in the order.
paymentPlatform	String	Optional. The target payment platform. Set to "COD" for Cash on Delivery.
items	Array	An array of item objects being checked out. See structure below.

items Array Object Fields

Field	Type	Description
itemCode	String	The unique code of the item in the cart.
description1-20	String	Optional. Up to 20 custom description fields for this specific item.

Example 1: Delivery to Address with Contact Info JSON

{
  "addressCode": "address",
  "billingAddressCode": "address2",
  "firstName": "Francisco",
  "lastName": "Alvarez",
  "contactNumber": "1133557799",
  "status": "CHECKOUT_PAYMENT_PROCESSING",
  "referringPrincipal": "[email protected]",
  "items": [
    {
      "itemCode": "p1",
      "description": "Custom item description"
    }
  ]
}

Example 2: Delivery to Exchange Center JSON

{
  "exchangeCenterId": 1,
  "status": "CHECKOUT_PAYMENT_PROCESSING",
  "items": [
    {
      "itemCode": "p1"
    }
  ]
}

---

Response

✅ Successful Response: 200 OK

The checkout and payment record were successfully created. The response contains an array of the generated orders and a payment object.

orders Object Fields

Field	Type	Description
orderNumber	Integer	The unique number for the generated order.
orderState	String	The current state of the order (e.g., "Received").
total	Number	The total point cost of the order.
shippingAddress	Object	The resolved shipping address object.
billingAddress	Object	The resolved billing address object.
items	Array	An array of item objects included in this order.

payment Object Fields

Field	Type	Description
paymentReference	String	A unique reference code for this payment transaction.
state	String	The initial state of the payment (e.g., "New").
amount	Number	The monetary amount to be paid.

JSON

{
  "orders": [
    {
      "orderNumber": 49,
      "creationDate": 1636574827602,
      "orderState": "Received",
      "exchangeCenterId": 1,
      "total": 0.0,
      "billingAddress": {
        "id": 130,
        "street1": "Street1 alternativa"
      },
      "items": [
        {
          "item": {
            "code": "p1",
            "name": "papas baston"
          },
          "quantity": 2,
          "total": 0.0
        }
      ],
      "discountCupons": []
    }
  ],
  "payment": {
    "paymentReference": "26480182",
    "state": "New",
    "amount": 500.0,
    "lastInteractionDate": 1591650533382
  }
}

❌ Unsuccessful Response: 400 Bad Request

Returned for logical errors such as an empty cart, items out of stock, or an invalid referral code.

JSON

{
  "errors": {
    "cart": "IsEmpty",
    "item": "NotInStock",
    "checkout": "NotSpecifiedDeliveryMethod",
    "referringPrincipal": "InvalidReferringCode"
  }
}

❌ Unsuccessful Response: 404 Not Found

Returned if a specified resource like the activity, address, or exchange center does not exist.

JSON

{
  "errors": {
    "error.message": "NOT_FOUND",
    "address": "InvalidCode",
    "exchangeCenter": "InvalidID"
  }
}