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.

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

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.

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

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