Order 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.

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.
  • 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.
  • The financing request has been accepted by Aplazame and now confirmation is required from the store to complete the process.

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.

order-confirmation-ok
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 Description
id string Aplazame’s order identifier (immutable).
status string Order status (ok, pending or ko).
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 Aplazame is waiting for the buyer to complete an identity validation challenge after completing the financing request.
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.

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

{
  "status": "ok"
}

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