Creación del checkout

Petición

La creación del checkout se realizará mediante una petición POST al servidor de Aplazame.

tip

Esta página describe como crear un checkout para los productos que tenemos disponibles. Esto dependerá también de la configuración que tenga tu comercio en nuestro backend. Si no se indica tipo de producto en la request (primer caso descrito), se creará el que te corresponda según esa configuración.

Si estás iniciando la integración, te puede interesar consultar cómo establecer el modo de pruebas y también los datos de prueba disponibles para la integración. También disponemos de varios SDK para facilitar la creación del checkout:

• PHP SDK
• .NET SDK
• Node.js SDK

precaución

Recuerda visitar primeros pasos para obtener tu api_private_key.

La petición POST debe enviar los siguientes campos y cabeceras:

producción

POST https://api.aplazame.com/checkout
Accept: application/vnd.aplazame.v4+json
Authorization: Bearer api_private_key
Content-Type: application/json

{
  "merchant": {...},
  "order": {...},
  "customer": {...},
  "billing": {...},
  "shipping": {...}
}

pruebas

POST https://api.aplazame.com/checkout
Accept: application/vnd.aplazame.sandbox.v4+json
Authorization: Bearer api_private_key
Content-Type: application/json

{
  "merchant": {...},
  "order": {...},
  "customer": {...},
  "billing": {...},
  "shipping": {...}
}

PHP

$privateKey = 'api_private_key';
$environment = Aplazame\Api\Client::ENVIRONMENT_SANDBOX;
$apiBaseUri = 'https://api.aplazame.com';

$aplazameApiClient = new Aplazame\Api\Client($apiBaseUri, $environment, $privateKey);

$order_created = $aplazameApiClient->request('POST','/checkout', $payload, 4);

// como crear el payload del checkout:
// https://github.com/aplazame/php-sdk/blob/master/examples/step1_checkout_create.php#L39

node

const aplazame = require('@aplazame/node')({
  access_token: 'api_private_key',
  is_sandbox: true,
})

aplazame.post('/checkout', {
  "merchant": {...},
  "order": {...},
  "customer": {...},
  "billing": {...},
  "shipping": {...}
}).then(function (response) {

  console.log('Order created successfully!', response.headers.location)

}, function (response) {

  console.log('Error creating order:' + response.status)

})

shell

$ curl --request POST "https://api.aplazame.com/checkout" \
    --header "Accept: application/vnd.aplazame.v4+json" \
    --header "Authorization: Bearer api_private_key" \
    --data '{ "merchant": {...}, "order": {...}, "customer": {...}, "billing": {...}, "shipping": {...} }'

Parámetro	Tipo	Requerido	Descripción
merchant	object	Sí	Datos del merchant.
order	object	Sí	Datos del pedido.
customer	object	Sí	Datos del cliente.
billing	object	No	Dirección de facturación.
shipping	object	Sí	Información de envío.

Forzar modalidad de pago

Si no se especifica un campo product, el tipo de checkout por defecto será híbrido y se mostrarán todas las modalidades de pago disponibles. En caso de especificarse, se mostrará únicamente dicha modalidad sin dar opción al resto.

{
  ...
  "product": {
    "type": "pay_in_4"
  }
}

Parámetro	Tipo	Requerido	Descripción
product	object	No	Puede ser instalments (pago a plazos), pay_in_4 (pago en 4) o pay_later (pago en 15 días).

merchant

Campos relacionados con las redirecciones web, confirmación del pedido a través de la notification_url y tiempos de expiración.

{
  "merchant": {
    "notification_url": "https://merchant.com/order/confirm",
    "success_url": "/success",
    "pending_url": "/pending",
    "error_url": "/error",
    "dismiss_url": "/",
    "ko_url": "/ko",
    "close_on_success": false,
    "timeout_checkout": 60,
    "timeout_extra": 2880
  },
  // ...
}

Parámetro	Tipo	Requerido	Descripción
notification_url	url	Sí	URL a la que se notificará los cambios de estado del pedido y que servirá para completar la confirmación final.
success_url	url	Sí	URL (relativa a la tienda) a la que se redirigirá al usuario cuando se haya completado el pago.
pending_url	url	Sí	URL (relativa a la tienda) a la que se redirigirá al usuario cuando el pago quede pendiente de confirmación.
error_url	url	Sí	URL (relativa a la tienda) a la que se redirigirá al usuario cuando haya ocurrido un error.
dismiss_url	url	No	URL (relativa a la tienda) a la que se redirigirá al usuario cuando éste escoge volver a la tienda (por defecto '/').
ko_url	url	No	URL (relativa a la tienda) a la que se redirigirá al usuario cuando se haya denegado el pago.
close_on_success	boolean	No	Indica si el checkout se redirige automáticamente a success_url en caso de éxito (por omisión: false).
timeout_checkout	integer	No	Establece el tiempo máximo, en minutos, del que dispone el usuario para completar el proceso de checkout. (por omisión 60; mín. 1; máx. 120).
timeout_extra	integer	No	Establece el tiempo adicional, en minutos, del que dispone el usuario para completar la validación de identidad una vez finalizado el proceso de checkout. (por omisión 2880; mín. 0; máx. 2880).

order

Campos relacionados con el pedido, como su importe total y los artículos.

precaución

• Aplazame no permite diferentes pedidos con el mismo id.
• El campo total_amount debe ser igual a la suma total del precio de sus artículos y envío incluyendo impuestos y descuentos (ver apartado Importe total del pedido).

{
  "id": "28475648233786783165",
  "articles": [
    {
      "id": "89793238462643383279",
      "name": "Reloj en oro blanco de 18 quilates y diamantes",
      "quantity": 2,
      "price": 402000,
      "tax_rate": 2100,
      "discount": 2000,
      "description": "Movimiento de cuarzo de alta precisión",
      "url": "http://www.chanel.com/fragrance-beauty/Fragrance-N05-88145/sku/138083",
      "image_url": "http://www.chanel.com/fragrance-beauty/Fragrance-N05-88145/sku/138083/product_01.jpg"
    },
    ...
  ],
  "discount": 16000,
  "currency": "EUR",
  "total_amount": 462000,
  "tax_rate": 2100,
  "options": {...},
}

Parámetro	Tipo	Requerido	Descripción
id	string	Sí	ID del pedido.
discount	decimal	No	Importe de descuento en el precio del pedido.
discount_rate	decimal	No	Tasa de descuento en el precio del pedido.
cart_discount	decimal	No	Importe de descuento en el precio del carrito.
cart_discount_rate	decimal	No	Tasa de descuento en el precio del carrito.
currency	ISO 4217	Sí	Código de la moneda del pedido.
total_amount	decimal	Sí	Cantidad a financiar.
tax_rate	decimal	Sí	Tasa de impuesto en el precio del pedido.
options	object	No	Permite definir opciones concretas de esta order, por ejemplo, la fecha del primer pago.
articles	collection	Sí	Artículos en el carrito.

tax_rate

Cada artículo del pedido debe tener tax_rate. Alternativamente puedes incluirlo globalmente en order.tax_rate o puedes aplicarlo a cada artículo y envío.

precaución

El tax_rate en cada artículo o envío sobreescribe el valor global si existe.

options

{
  "event_date": "2021-06-15"
}

Parámetro	Tipo	Requerido	Descripción
event_date	ISO 8601	No	Permite definir la fecha en la que se va a disfrutar del producto comprado, por ejemplo: fecha de un viaje o comienzo de un curso.

article

{
  "id": "89793238462643383279",
  "name": "Reloj en oro blanco de 18 quilates y diamantes",
  "quantity": 2,
  "price": 402000,
  "tax_rate": 2100,
  "discount": 2000,
  "description": "Movimiento de cuarzo de alta precisión",
  "url": "http://www.chanel.com/fragrance-beauty/Fragrance-N05-88145/sku/138083",
  "image_url": "http://www.chanel.com/fragrance-beauty/Fragrance-N05-88145/sku/138083/product_01.jpg",
  "category": "Joyería"
}

Parámetro	Tipo	Requerido	Descripción
id	string	Sí	ID.
name	string	Sí	Nombre.
description	string	No	Descripción.
url	URL	Sí	URL absoluta del artículo.
image_url	URL	Sí	URL absoluta de la imagen del artículo.
quantity	integer	Sí	Cantidad.
price	decimal	Sí	Precio (sin impuestos).
tax_rate	decimal	No	Tasa de impuestos en el precio.
discount	decimal	No	Importe de descuento en el precio.
discount_rate	decimal	No	Tasa de descuento en el precio.
category	string	No	Categoría del artículo.

customer

Campos realacionados con los datos del cliente.

{
  "id": "1618",
  "email": "customer@address.com",
  "document": { "number": "12345678X" }
  "type": "e",
  "gender": 0,
  "first_name": "John",
  "last_name": "Coltrane",
  "birthday": "1980-01-01",
  "phone": "601234567",
  "language": "es",
  "date_joined": "2014-08-21T13:56:45+0000",
  "last_login": "2020-08-27T19:57:56+0000",
  "address": {
    "phone": "601234567",
    "street": "Plaza del Valle Boreal nº10",
    "address_addition": "Cerca de la plaza Pontífice Sulyvahn",
    "city": "Madrid",
    "state": "Madrid",
    "country": "ES",
    "postcode": "28080"
  }
}

Parámetro	Tipo	Requerido	Descripción
id	string	No	ID del cliente.
email	string	Sí	Correo del cliente.
document	object	No	Indica el documento de identidad del cliente.
address	object	No	Dirección.
type	char	No	Tipo de cliente; las opciones son g invitado, n nuevo, e existente.
gender	integer	No	Género; las opciones son 0 desconocido, 1 hombre, 2 mujer, 3 no aplica.
first_name	string	No	Nombre.
last_name	string	No	Apellidos.
phone	string	No	Número de teléfono del cliente.
birthday	ISO 8601	No	Fecha de nacimiento.
language	ISO 639-1	No	Preferencias de idioma.
date_joined	ISO 8601	No	Fecha que designa cuando se creó la cuenta.
last_login	ISO 8601	No	Fecha del último inicio de sesión.

document

{
  "number": "12345678X"
}

Parámetro	Tipo	Requerido	Descripción
number	string	Sí	Número de DNI o NIE.

address

{
  "phone": "601234567",
  "street": "Plaza del Valle Boreal nº10",
  "address_addition": "Cerca de la plaza Pontífice Sulyvahn",
  "city": "Madrid",
  "state": "Madrid",
  "country": "ES",
  "postcode": "28080"
}

Parámetro	Tipo	Requerido	Descripción
phone	string	No	Número de teléfono de la dirección.
alt_phone	string	No	Número de teléfono alternativo.
street	string	Sí	Dirección.
address_addition	string	No	Línea adicional.
city	string	Sí	Municipio / ciudad.
state	string	Sí	Estado / provincia.
country	ISO 3166-1	Sí	Código de país.
postcode	string	Sí	Código postal.

billing

Campos relacionados con los datos de facturación del pedido.

{
  "first_name": "Bill",
  "last_name": "Evans",
  "phone": "601765432",
  "street": "Calle Central Yharnam 92",
  "address_addition": "Cerca del Gran Puente",
  "city": "Madrid",
  "state": "Madrid",
  "country": "ES",
  "postcode": "28080"
}

Parámetro	Tipo	Requerido	Descripción
first_name	string	Sí	Nombre.
last_name	string	Sí	Apellido.
phone	string	No	Número de teléfono de la dirección.
alt_phone	string	No	Número de teléfono alternativo.
street	string	Sí	Dirección.
address_addition	string	No	Línea adicional.
city	string	Sí	Municipio / ciudad.
state	string	Sí	Estado / provincia.
country	ISO 3166-1	Sí	Código de país.
postcode	string	Sí	Código postal.

shipping

Campos relacionados con el envío del pedido.

{
  "first_name": "Django",
  "last_name": "Reinhard",
  "phone": "601234567",
  "street": "Plaza del Valle Boreal nº10",
  "address_addition": "Cerca de la plaza Pontífice Sulyvahn",
  "city": "Madrid",
  "state": "Madrid",
  "country": "ES",
  "postcode": "28080",
  "price": 500,
  "tax_rate": 2100,
  "name": "Planet Express",
  "discount": 100,
  "method": "postal"
}

Parámetro	Tipo	Requerido	Descripción
first_name	string	Sí	Nombre.
last_name	string	Sí	Apellido.
phone	string	No	Número de teléfono de la dirección.
alt_phone	string	No	Número de teléfono alternativo.
street	string	Sí	Dirección.
address_addition	string	No	Línea adicional.
city	string	Sí	Municipio / ciudad.
state	string	Sí	Estado / provincia.
country	ISO 3166-1	Sí	Código de país.
postcode	string	Sí	Código postal.
name	string	Sí	Nombre del envío.
price	decimal	Sí	Precio del envío (impuestos no incluidos).
tax_rate	decimal	No	Tasa de impuestos en el precio del envío.
discount	decimal	No	Cantidad de descuento en el precio del envío.
discount_rate	decimal	No	Tasa de descuento en el precio del envío.
method	string	No	Método de envío; las opciones son pickup_store recogida en tienda, pickup_point punto de recogida, postal envio por correo.

Importe total del pedido

Es importante que el importe total del pedido (indicado por total_amount en la lista order) sea el sumatorio de lo siguente:

• El precio de todos los artículos (precio sin impuestos price + porcentaje de impuestos tax_rate - descuentos discount) de la lista articles.
• El precio del envío (precio sin impuestos price + porcentaje de impuestos tax_rate - descuentos discount) de la lista shipping.

info

Alternativamente también se puede incluir un sólo campo discount en la lista order (fuera de articles) que sume todos los descuentos.