1. Ayuda
  2. Desarrolladores
  3. Checkouts API
Regresar

Checkouts API

El checkout es la transición de un carrito a una orden.

Para generar y modificar checkouts es necesario agregar el header Channel-Key, que se muestra en la vista del canal API dentro del administrador.

Objeto de Checkout

La estructura de la respuesta está dividida en dos partes:

{
  "meta": {
    ...
  },
  "data": {
    ...
  }
}

Sección meta

Atributo Tipo Descripción
is_shipping_required boleano Indica si la orden necesita método de envío.
selected_shipping_method cadena Indica el método de envío asignado al checkout.
selected_payment_gateway cadena Indica el método de pago asignado al checkout.
shipping_methods[] arreglo Lista todos los métodos de envío que son utilizables por la orden con base en su costo total y/o peso de envío.
payment_gateways[] arreglo Lista todos los métodos de pago utilizables para la orden.

Sección data

El contenido de data es una orden. Consulta la documentación de Órdenes para ver la estructura del objeto.

Recursos para Checkout

Recursos para direcciones

Para llenar la información de dirección de pago y/o envío es necesario utilizar los códigos de paises y estados/regiones como se indican en los siguiente endpoints.

Las solicitudes a estos recursos dependen de las particularidades de la tienda, por ejemplo, si ésta solo vende en México únicamente se requiere solicitar al endpoint de estados/regiones los pertenecientes al código MX.

GET /v1/countries

La estructura de la respuesta está dividida en dos partes:

{
  "billing_countries": [
    ...
    ],
  "shipping_countries": [
    ...
  ]
}

El valor de la llave code de los paises elegidos para envío y/o pago se usarán más adelante.

GET /v1/countries/{code}/states

El valor de la llave code de los estados elegidos para envío y/o pago se usarán más adelante. Si la lista de estados está vacía en lugar de utilizar el código, se enviará una cadena con el nombre correspondiente.

Gateways

Aun cuando las solicitudes de checkout regresan los gateways disponibles, es posible solicitarlos directamente.

GET /v1/gateways

Obtiene el listado de gateways de pago disponibles.

GET /v1/gateways/{id}

Obtiene información de un gateway de pago.

Creación / actualización de Checkout

Dependiendo de las particularidades de la tienda posible saber o ignorar a priori ciertos valores necesarios para asignar los métodos de pago y envío.

Si la implementación es para una tienda quw solo vende en México productos que requiren envío, luego de solicitar los estados al endpoint es posible generar una vista donde se capturen todos los datos: información del comprador, la direcciones de envío y opcionalmente la dirección de pago, generando y llenando la información de checkout en un solo paso.

Si por el contrario, los paises son variables y/o se venden productos que pueden o no requerir envío, será necesario crear un checkout sin enviar datos y con base en la información meta respondida saber que elementos agregar a la vista de captura para enviar al endpoint de actualización.

POST /v1/carts/{cartId}/checkout
PUT /v1/checkouts/{orderId}

Carga útil

Un objeto con los siguientes elementos:

Nombre Tipo Default Requerido Descripción
customer[email] cadena true El email del comprador.
customer[first_name] cadena false El/los nombre(s) del comprador.
customer[last_name] cadena false El/los apellido(s) del comprador.
customer[is_newsletterable] boleano false false Indica si el email del comprador puede ser usado para enviar newsletters.
shipping[first_name] cadena true El/los nombre(s) para la dirección de envío.
shipping[last_name] cadena true El/los apellido(s) para la dirección de envío.
shipping[address1] cadena true La información principal de envío, calle, número exterior e interior, etc.
shipping[address2] cadena false Campo extra para dirección como colonia, barrio, etc.
shipping[references] cadena false Referencias de la drección de envío como edificios cercanos, entre que calles se encuentra, etc.
shipping[company] cadena false La compañía a la que pertenece la dirección de envío.
shipping[postcode] cadena true El código postal de la dirección de envío.
shipping[city] cadena true La ciudad de la dirección de envío.
shipping[country_code] cadena true El código de país de la dirección de envío, obtenido desde /v1/countries.
shipping[state_code] cadena false El código de estado de la dirección de envío, obtenido desde /v1/countries/{code}/states.
shipping[state] cadena false El nombre del estado de la dirección de envío (requerido si no hay un código de estado disponible).
shipping[phone] cadena true El teléfono de la dirección de envío.
shipping[id] cadena false El ID de alguna dirección perteneciente al cliente. Cuando se especifica, los otros datos de shipping se ignoran
same_address boleano true false Indica si se usará la misma dirección de envío como dirección de pago.
billing[first_name] cadena true El/los nombre(s) para la dirección de pago.
billing[last_name] cadena true El/los apellido(s) para la dirección de pago.
billing[address1] cadena true La información principal de envío, calle, número exterior e interior, etc.
billing[address2] cadena false Campo extra para dirección como colonia, barrio, etc.
billing[company] cadena false La compañía a la que pertenece la dirección de pago.
billing[postcode] cadena true El código postal de la dirección de pago.
billing[city] cadena true La ciudad de la dirección de pago.
billing[country_code] cadena true El código de país de la dirección de pago, obtenido desde /v1/countries.
billing[state_code] cadena false El código de estado de la dirección de pago, obtenido desde /v1/countries/{code}/states.
billing[state] cadena false El nombre del estado de la dirección de pago (requerido si no hay un código de estado disponible).
billing[phone] cadena true El teléfono de la dirección de pago.
billing[id] cadena false El ID de alguna dirección perteneciente al cliente. Cuando se especifica, los otros datos de billing se ignoran

La validación y asignación de información del comprador se realiza si existe al menos algún elemento de la estructura customer. La validación y asignación de dirección de envío se realiza si existe al menos algún elemento de la estructura shipping. La validación y asignación de dirección de pago se realiza si se envía el elemento same_address con valor falso.

Ejemplos

Creación de checkout sin enviar información, esto sirve cuando no se tiene ningún tipo de información previa.

{
}

Creación/actualización de checkout con los datos mínimos del comprador.

{
    "customer": {
        "email": "juantremendo@example.com"
    }
}

Creación/actualización de checkout con los datos mínimos de dirección.

{
    "shipping": {
        "first_name": "Juan",
        "last_name": "Tremendo",
        "address1": "5 norte No.9, int 6. Col Centro.",
        "postcode": "72000",
        "city": "Puebla",
        "country_code": "MX",
        "state_code": "PUE",
        "phone": "1234567890"
    }
}

Creación/actualización de checkout con todos los datos.

{
    "customer": {
        "email": "juantremendo@example.com",
        "first_name": "Juan",
        "last_name": "Tremendo",
        "is_newsletterable": true
    },
    "shipping": {
        "first_name": "Juan",
        "last_name": "Tremendo",
        "address1": "5 norte No.9, int 6",
        "address2": "Centro",
        "references": "Frente al colegio",
        "company": "Tremens LTD",
        "postcode": "72550",
        "city": "Puebla",
        "country_code": "MX",
        "state_code": "PUE",
        "phone": "1234567890"
    },
    "same_address": false,
    "billing": {
        "first_name": "Juan Pedro",
        "last_name": "Pérez Pérez",
        "address1": "25 oriente #2520 - 3",
        "address2": "Plateros",
        "company": "Tronic SA de CV",
        "postcode": "72200",
        "city": "Puebla",
        "country_code": "MX",
        "state_code": "PUE",
        "phone": "1212121212"
    }
}

Adición de direcciones de envío y pago usando direcciones del cliente.

{
    "shipping": {
        "id": "adr_cjg2wni720001x0o2oo2uceah"
    },
    "billing": {
        "id": "adr_cjg3tvrf60004koo2mj4s94ep"
    }
}
{
    "shipping": {
        "id": "adr_cjg2wni720001x0o2oo2uceah"
    },
    "same_address": true
}

Si la orden no require envío, se puede enviar solamente la dirección de pago.

{
    "billing": ...
}

la respuesta es la misma que al Consultar un Checkout.

Consultar un Checkout

GET /v1/checkouts/{id}
{
  "meta": {
    "is_shipping_required": true,
    "selected_shipping_method": null,
    "selected_payment_gateway": null,
    "shipping_methods": [
      {
        "id": "shr_cjg8mcqbt002z13o2u9rgrgc9",
        "kind": "weight",
        "name": "Env\u00edo est\u00e1ndar",
        "from": 0,
        "to": 500,
        "price": 10000,
        "object": "shipping_zone_rate",
        "store": {
          "id": "str_cjg8mcazg000013o2bob3fq25",
          "subdomain": "store1",
          "domain": "store1.kometia.test",
          "name": "store1",
          "description": null,
          "image": null,
          "store_status": "active",
          "email": "user1@mail.com",
          "address1": "Calle Falsa 123",
          "address2": "Colonia",
          "postcode": "12345",
          "city": "Delegaci\u00f3n",
          "country": "Mexico",
          "country_code": "MX",
          "state": "Puebla",
          "state_code": "PUE",
          "references": null,
          "phone": "1234567890",
          "tax_id": null,
          "business_name": null,
          "fiscal_address": null,
          "contact_email": "user1@mail.com",
          "lang": "es",
          "currency": "MXN",
          "timezone": "America\/Mexico_City",
          "weight_unit": "kg",
          "order_prefix": null,
          "order_suffix": null,
          "is_tax_included": true,
          "billing_gateway_source": null,
          "billing_customer_id": null,
          "billing_card_brand": null,
          "billing_card_last_four": null,
          "billing_card_exp_month": null,
          "billing_card_exp_year": null,
          "billing_invoice_custom_data": null,
          "next_billing_at": "2018-05-06 12:00:00",
          "created_at": "2018-04-21 00:01:30",
          "updated_at": "2018-04-21 00:01:50",
          "object": "store"
        }
      }
    ],
    "payment_gateways": []
  },
  "data": {
    "id": "ord_cjgfqxb1p00000vo2vsyefadg",
    "object": "order",
    "number": null,
    "status": "created",
    "financial_status": "unpaid",
    "fulfillment_status": "unfulfilled",
    "email": "juantremendo@example.com",
    "customer": {
      "id": "cus_cjgfqxc9t00050vo2umuift5m",
      "object": "customer",
      "name": "Juan Tremendo",
      "first_name": "Juan",
      "last_name": "Tremendo",
      "email": "juantremendo@example.com",
      "is_newsletterable": true,
      "is_active": false,
      "notes": null,
      "tags": [],
      "created_at": 1524699853,
      "updated_at": 1524699853
    },
    "items": [
      {
        "id": "itm_cjgfqxbr100030vo2kz0ccdmx",
        "object": "order_item",
        "permalink": "test-shirt",
        "name": "Test Shirt 1",
        "product_name": "Test Shirt",
        "sku_name": "1",
        "vendor": null,
        "code": null,
        "image": null,
        "price": 15000,
        "compared_price": 0,
        "quantity": 2,
        "discount": null,
        "is_taxable": true,
        "tax_rate": 1600,
        "subtotal": 25862,
        "taxes": 4138,
        "total": 30000,
        "fulfilled": 0,
        "is_shipping_required": true,
        "weight": 2000,
        "stock_id": null,
        "order_id": "ord_cjgfqxb1p00000vo2vsyefadg",
        "product_id": "prd_cjgff0zr0000013o20rfypz7v",
        "sku_id": "sku_cjgff0zsp000113o29zwjilz8",
        "stock_manager": [],
        "created_at": 1524699852,
        "updated_at": 1524699852
      },
      {
        "id": "itm_cjgfqxbjn00020vo2y9oet7qh",
        "object": "order_item",
        "permalink": "test-product",
        "name": "Test Product",
        "product_name": "Test Product",
        "sku_name": "",
        "vendor": null,
        "code": null,
        "image": null,
        "price": 10000,
        "compared_price": 0,
        "quantity": 1,
        "discount": null,
        "is_taxable": false,
        "tax_rate": 1600,
        "subtotal": 10000,
        "taxes": 0,
        "total": 10000,
        "fulfilled": 0,
        "is_shipping_required": true,
        "weight": 1000,
        "stock_id": null,
        "order_id": "ord_cjgfqxb1p00000vo2vsyefadg",
        "product_id": "prd_cjgff061n000013o22ef8a508",
        "sku_id": "sku_cjgff06q9000113o2wzmfyvzq",
        "stock_manager": [],
        "created_at": 1524699852,
        "updated_at": 1524699852
      }
    ],
    "is_shipping_required": true,
    "shipping_lines": null,
    "shipping_rate": 0,
    "shipping": {
      "address": {
        "city": "Puebla",
        "country": "Mexico",
        "country_code": "MX",
        "address1": "Calle Cadillac #27",
        "address2": "Lomas de San Juan",
        "postcode": "72550",
        "state": "Puebla",
        "state_code": "PUE"
      },
      "name": "Juan Tremendo",
      "phone": "1234567890"
    },
    "billing": {
      "address": {
        "city": "Puebla",
        "country": "Mexico",
        "country_code": "MX",
        "address1": "25 oriente #2520 - 3",
        "address2": "Plateros",
        "postcode": "72200",
        "state": "Puebla",
        "state_code": "PUE"
      },
      "name": "Pedro P\u00e1ramo",
      "phone": "1212121212"
    },
    "discount_codes": null,
    "is_gift": true,
    "gift_message": "Regalito",
    "source_name": "api",
    "customer_note": "Verificar acabado",
    "order_note": null,
    "cancel_reason": null,
    "browser_ip": "127.0.0.1",
    "user_agent": "rest-client",
    "landing_site": "",
    "referring_site": "",
    "gateway": null,
    "total_products": 2,
    "total_discount": 0,
    "total_items": 3,
    "total_items_price": 35862,
    "subtotal_price": 40000,
    "total_taxes": 4138,
    "total_price": 40000,
    "currency": "MXN",
    "total_weight": 5000,
    "transactions": [],
    "is_test": null,
    "customer_id": "cus_cjgfqxc9t00050vo2umuift5m",
    "channel_id": "chn_cjgfds0g9000013o28ww9vlj5",
    "cart_id": "crt_cjgfgqad3000013o2v8dzo0s7",
    "canceler_id": null,
    "placed_at": null,
    "archived_at": null,
    "canceled_at": null,
    "created_at": 1524699851,
    "updated_at": 1524700183
  }
}

Asignar métodos de pago y envío al Checkout

POST /v1/checkouts/{id}/methods

Carga útil

Un objeto con los siguientes elementos:

Nombre Tipo Requerido Descripción
shipping[method] cadena false El id del método de envío elegido. Se debe enviar cuando meta[is_shipping_required] sea verdadero.
payment[gateway] cadena true El id del gateway de pago elegido.

Pagar la orden del Checkout

POST /v1/checkouts/{id}/payment

Carga útil

Un objeto con los siguientes elementos:

Nombre Tipo Requerido Descripción
payment[method] cadena true El método de pago para el gateway elegido.