Checkout creation

Request

The creation of the checkout will be done by means of a POST request to the Aplazame server.

tip

This page describes how to create a checkout for the products we have available. This will also depend on the configuration that your trade has in our backend. If the type of product is not indicated in the request (first case described), the one that corresponds to you will be created according to that configuration.

If you are starting the integration you may be interested in how to set the test mode as well as test data available for the integration. We also have several SDKs to facilitate the checkout checkout:

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

caution

Before starting integration, we recommend you visit our first steps section to complete the registration process and obtain your api_private_key.

POST request should have next fields and headers:

production

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": {...}
}

tests

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);

// checkout how to create the payload:
// 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": {...} }'

Parameter	Type	Required	Description
merchant	object	Yes	Merchant data.
order	object	Yes	Your order data.
customer	object	Yes	Customer data.
billing	object	No	Billing address.
shipping	object	Yes	Shipping info.

Force payment method

If a product field is not specified, the default checkout type will be hybrid and all available payment methods will be displayed. If specified, only this modality will be shown without giving the rest options.

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

Parameter	Type	Required	Description
product	object	No	It can be instalments (instalments payment), pay_in_4 (pay in 4) or pay_later (payment in 15 days).

merchant

Fields related to web redirects, checkout confirmation via notification_url and expiration times.

{
  "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
  },
  // ...
}

Parameter	Type	Required	Description
notification_url	url	Yes	URL to be notified of changes to the status of the order and which will serve to complete the final confirmation.
success_url	url	Yes	URL (relating to the store) to which the user will be redirected when payment has been completed.
pending_url	url	Yes	URL (relating to the store) to which the user will be redirected when the payment is pending confirmation.
error_url	url	Yes	URL (relating to the store) to which the user will be redirected when an error has occurred.
dismiss_url	url	No	URL (relating to the store) to which the user will be redirected when they choose to return to the store (by default '/').
ko_url	url	No	URL (relating to the store) to which the user will be redirected when payment has been denied.
close_on_success	boolean	No	Indicates whether the checkout automatically redirects you to the success_url in case of success. (by default: false).
timeout_checkout	integer	No	It establishes the maximum time, in minutes, that the user has to complete the checkout process (by default 60; min. 1; max. 120).
timeout_extra	integer	No	It establishes the additional time, in minutes, that the user has to complete the identity validation task once the checkout process is finished (by default 2880; min. 0; max. 2880).

order

Fields related to the order, such as its total amount and items.

caution

• Aplazame does not allow different orders with the same id.
• The total_amount field must be equal to the total sum of the price of your items and shipping including taxes and discounts (see section Total order amount).

{
  "id": "28475648233786783165",
  "articles": [
    {
      "id": "89793238462643383279",
      "name": "18 ct white gold watch with diamonds",
      "quantity": 2,
      "price": 402000,
      "tax_rate": 2100,
      "discount": 2000,
      "description": "High-precision quartz movement",
      "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": {...},
}

Parameter	Type	Required	Description
id	string	Yes	Your order ID.
discount	decimal	No	Discount amount of the order.
discount_rate	decimal	No	Discount rate on the price of the order.
cart_discount	decimal	No	Discount amount of the cart.
cart_discount_rate	decimal	No	Discount rate of the cart.
currency	ISO 4217	Yes	Currency code of the order.
total_amount	decimal	Yes	Total order amount.
tax_rate	decimal	Yes	Order tax rate.
options	object	No	It allows defining specific options for this order, for example, the date of the first payment.
articles	collection	Yes	Articles in cart.

tax_rate

All order items must have a tax rate tax_rate. You can include this rate globally in order.tax_rate or you can choose to apply the rate to each individual item and shipping.

caution

The tax_rate of each individual item or shipping overrides the global tax rate defined.

options

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

Parameter	Type	Required	Description
event_date	ISO 8601	No	It allows defining the date on which the purchased product will be enjoyed, for example: date of a trip or start of a course.

article

{
  "id": "89793238462643383279",
  "name": "18 ct white gold watch with diamonds",
  "quantity": 2,
  "price": 402000,
  "tax_rate": 2100,
  "discount": 2000,
  "description": "High-precision quartz movement",
  "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": "Jewelry"
}

Parameter	Type	Required	Description
id	string	Yes	ID.
name	string	Yes	Name.
description	string	No	Description.
url	URL	Yes	Article absolute URL.
image_url	URL	Yes	Article image absolute URL.
quantity	integer	Yes	Quantity.
price	decimal	Yes	Price (tax not included).
tax_rate	decimal	No	Tax rate.
discount	decimal	No	Discount amount.
discount_rate	decimal	No	Discount rate.
category	string	No	Category of the article.

customer

Fields related to customer data.

{
  "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": "en",
  "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": "Near Pontiff Sulyvahn's Plaza",
    "city": "Madrid",
    "state": "Madrid",
    "country": "ES",
    "postcode": "28080"
  }
}

Parameter	Type	Required	Description
id	string	No	ID del cliente
email	string	Yes	Customer email.
document	object	No	The customer's identity document.
address	object	No	Address.
type	char	No	Customer type; the choices are g guest, n new, e existing.
gender	integer	No	Gender; the choices are 0 not known, 1 male, 2 female, 3 not applicable.
first_name	string	No	First name.
last_name	string	No	Last name.
phone	string	No	Client phone number.
birthday	ISO 8601	No	Date of birth.
language	ISO 639-1	No	Language preferences.
date_joined	ISO 8601	No	Date designating when the customer account was created.
last_login	ISO 8601	No	Date of the customer's last login.

document

{
  "number": "12345678X",
  "nif_number": "123456789"
}

Parameter	Type	Required	Description
number	string	Yes	Identification number.
nif_number	string	No	NIF number (only for Portugal).

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"
}

Parameter	Type	Required	Description
phone	string	No	Phone number.
alt_phone	string	No	Alternative phone number.
street	string	Yes	Address.
address_addition	string	No	Additional line.
city	string	Yes	Town/city.
state	string	Yes	State/province.
country	ISO 3166-1	Yes	Country code.
postcode	string	Yes	Post code.

billing

Fields related to the order billing data.

{
  "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"
}

Parameter	Type	Required	Description
first_name	string	Yes	First name.
last_name	string	Yes	Last name.
phone	string	No	Número de teléfono de la dirección.
alt_phone	string	No	Número de teléfono alternativo.
street	string	Yes	Dirección.
address_addition	string	No	Línea adicional.
city	string	Yes	Municipio / ciudad.
state	string	Yes	Estado / provincia.
country	ISO 3166-1	Yes	Código de país.
postcode	string	Yes	Código postal.

shipping

Fields related to the shipment of the order.

{
  "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"
}

Parameter	Type	Required	Description
first_name	string	Yes	First name.
last_name	string	Yes	Last name.
phone	string	No	Address phone number.
alt_phone	string	No	Alternative phone number.
street	string	Yes	Address.
address_addition	string	No	Additional line.
city	string	Yes	Town/ city.
state	string	Yes	State/ province.
country	ISO 3166-1	Yes	Country code.
postcode	string	Yes	Shipping postcode.
name	string	Yes	Shipping name.
price	decimal	Yes	Shipping price (tax is not included).
tax_rate	decimal	No	Shipping tax rate.
discount	decimal	No	Discount amount of the shipping.
discount_rate	decimal	No	Discount rate of the shipping.
method	string	No	Shipping method; choices are pickup_store, pickup_point, postal.

Total order amount

It's important that the total amount of the order (indicated by total_amount in the order list) is the sum of the following:

• The price of all items (price without tax price + tax percentage tax_rate - discounts discount) from the list articles.
• The shipping price (price without tax price + tax percentage tax_rate - discounts discount) from the list shipping.

info

Alternatively you can also include a single discount field in the list order (outside of articles) that sums up all the discounts.