Checkout confirmation

Aplazame uses the callback URL defined in the creation of the checkout as notification_url to provide notifications of relevant changes in the status of the order. The store must implement an endpoint at the address provided in order to respond to notifications.

info

Specifically, when the buyer completes the payment process and the status of the order is pending confirmation, Aplazame will send the result of the financing request to this address for confirmation by the store.

The confirmation notification is the last step that occurs once Aplazame has accepted the buyer's financing request, and determines whether the order will finally be processed. Once the order has been confirmed by the store, the application process will be completed and the payment will be made to the store.

Order confirmation

Once the financing request is completed, Aplazame will send a notification to the address notification_url. Aplazame expects the business to respond to all notifications sent in the appropriate response format.

There are three possible scenarios as a result of the buyer's financing request:

The financing request has been denied by Aplazame.

info

In the case of a denied request, the store will receive a notification, the status of which is ko.

The financing request is pending since Aplazame requires the buyer to complete an identity validation task. Meanwhile, the store must reserve the product for the buyer until the final status of the order is determined.

info

In case of a pending application for identity validation, the store will receive a notification whose status is pending and status_reason is challenge_required.

The financing request has been accepted by Aplazame and now confirmation is required from the store to complete the process.

info

In case of an approved request, the store will receive a notification whose status is pending and status_reason is confirmation_required.

The store must respond to the confirmation notification by reporting whether the order is finally accepted or denied (e.g.: the product is no longer in stock).

Depending on the response of the store, Aplazame will make a final additional notification to report on the final status of the order. In case any of the notifications sent do not obtain a response or do not have the expected format, Aplazame will perform a series of retries whose limit will be determined by the maximum expiry time of the order.

info

See the confirmation flow for an order that the store confirms after being accepted by Aplazame

order-confirmation-ok

info

See also the confirmation flow for an order that the store decides to reject after being accepted by Aplazame

order-confirmation-ko

Notification data

Each Aplazame notification includes the following information relevant to the status of the order.

See that the notifications sent by Aplazame include the store's private code as an authentication header. It is recommended to implement a mechanism to check the contents of the header in the store’s server and verify that the issuer of the notifications is Aplazame.

POST notification_url
Authorization: Bearer api_private_key
Content-Type: application/json

{
  "id": "8606a585a5a56e51856e7f6d84a131b8",
  "status": "pending",
  "status_reason": "confirmation_required",
  "sandbox": false,
  "mid": "nOIpXXVTSGhc",
  "total_amount": 124560,
  "tax_rate": 2100,
  "discount": 0,
  "discount_rate": 0,
  "currency": {
    "name": "Euro",
    "code": "EUR",
    "numeric": "978",
    "symbol": "€"
  },
  "rejected": false,
  "confirmed": null,
  "verified": "2017-09-11T15:47:12.503341Z",
  "expired": null,
  "expires_at": "2017-09-11T17:47:21.603326Z",
  "cancelled": null,
  "created": "2017-09-11T15:47:21.603326Z"
}

Parameter	Type	Required
id	string	Aplazame’s order identifier (immutable).
status	string	Order status (`ok`, `pending` o `ko`).
Order status reason.
status_reason	string	Order status reason.
sandbox	boolean	The order was placed in the test environment.
mid	string	Order identifier generated by the store or generated automatically by Aplazame.
total_amount	decimal	Quantity to be financed.
tax_rate	decimal	Discount amount on the price of the order.
discount	decimal	Discount amount on the price of the order.
discount_rate	decimal	Discount rate on the price of the order.
currency	ISO 4217	Order currency.
rejected	boolean	The request has been rejected.
confirmed	ISO 8601	Date and time of order confirmation.
verified	ISO 8601	Date and time of order verification.
expired	ISO 8601	Date and time of when the order expired.
expires_at	ISO 8601	Date and time of order expiry.
cancelled	ISO 8601	Date and time of order cancellation.
created	ISO 8601	Date and time of order creation.

Order status codes

The status of the order is reported in the status and status_reason fields. Depending on the status field of the order, the status_reason field provides specific information to determine the status of the order.

A pending status order means that the final status of the order has not yet been determined, which depends on an action on the part of the store, the buyer or Aplazame. Therefore, this is not a final status of an order.
An ok status order means that the order has been accepted and confirmed by both the store and by Aplazame. This is a final status of an order.
A ko status order means that the order has been rejected by Aplazame or cancelled by the store. This is a final status of an order.

Status	Status reason	Cause
pending	confirmation_required	The financing request has been accepted by Aplazame which is now waiting for final confirmation from the store.
pending	challenge_required	The financing request has been accepted by Aplazame which is now waiting for final confirmation from the store.
ko	expired	The financing request has expired.
ko	expired_challenge	The buyer has not passed the identity validation challenge within the allocated time.
ko	ko_generic	The financing request has not passed the Aplazame admission criteria.
ko	failed_challenge	The buyer has not passed the identity validation challenge.
ko	confirmation_rejected_by_merchant	The store has rejected the order.
ko	merchant_failed_to_confirm	Confirmation with the store was not possible.
ok		The financing request has been completed and accepted by the store.

Response format

Aplazame uses a simple response format for notification requests sent to the store. With the exception of the confirmation notification, Aplazame expects that the format of the response will always be an HTTP 200 OK with an ok status as response data. In any other case, Aplazame will perform several retries of delivery of the notification.

caution

In the case of the confirmation notification, the store will also respond with an HTTP 200 OK but the response data may include an ok status to proceed with the order confirmation or a ko status to deny it.

OK
KO
update order id

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "ok"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "ko"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "ok",
  "order_id": "28475648233786783165"
}

Optionally, only in the case of proceeding to the order confirmation, the response can include the updated identifier of the order (order_id) generated by the store in the confirmation transaction.

This identifier will be used to replace the provisional identifier assigned to the order before its confirmation (mid). Once Aplazame has received the order confirmation, it is not possible to change the identifier.

Confirmation algorithm

Confirmation example in pseudo-code for the store’s server

IF private_key != request.HEADER['Authorization'] THEN:
  RETURN Response(status_code = 403)
END IF

SET payload to JSON.Decode(request.POST)
IF payload.mid not found THEN:
  RETURN Response(status_code = 404)
END IF

IF payload.status == 'pending' AND
   payload.status_reason == 'confirmation_required' THEN:
  IF order.do_payment_accept() THEN:
    RETURN Response(status_code = 200, body = '{"status": "ok"}')
  ELSE:
    RETURN Response(status_code = 200, body = '{"status": "ko"}')
  END IF
ELSE IF payload.status == 'ko' THEN:
  IF order.do_payment_cancel() THEN:
    RETURN Response(status_code = 200, body = '{"status": "ok"}')
  ELSE:
    RETURN Response(status_code = 200, body = '{"status": "ko"}')
  END IF
ELSE:
  RETURN Response(status_code = 200, body = '{"status": "ok"}')
END IF

Order confirmation​

Notification data​

Order status codes​

Response format​

Confirmation algorithm​

Order confirmation

Notification data

Order status codes

Response format

Confirmation algorithm