Asynchronous Refund

WARNING: This page is a document under construction, subject to change without notice, and still uncoupled from our full documentation. If you wish to access all our documentation, check here.

The asynchronous refund functionality changes how cancellations are handled. As a result, cancellations are no longer processed immediately. Instead, they enter an asynchronous processing queue waiting to be cancelled. This approach allows you to improve processing efficiency, especially in cases of high transaction volume.

Note: This functionality is only available for BIN.

In this modality, the initial refund response will be pending (PEN) and when processed it will have a confirmed (CON) or denied (NEG) status. In case of process failure, error status (ERR) would be returned.

Note: The asynchronous refund process is currently not supported for pre-authorizations.

Necessary configurations in Carat

The store will only be able to perform asynchronous cancellation if it has permission for this operation in the Carat back office. To do this, it is necessary to communicate to the Carat registration team about this specific demand.

Flow related to cancellation processes

This flow below exemplifies the flow, starting from payment and going until cancellation. Including webhook endpoints and transaction status checker.

sequenceDiagram
    participant L as Merchant;
    participant E as Carat;

    Note over L, E: Payment

    L ->>+ E: POST https://<carat url>/e-sitef/api/v2/payments/
    #note right of E: Ex: post body
    E ->>- L: json with payment data including nit and OK (status: CON)

    Note over L, E: Cancel/Refund

    L ->>+ E: POST https://<carat url>/e-sitef/api/v2/cancellations/{{nit}}
    E -->>- L: json with payment data including nit and OK (status: PEN)

    Note over L, E: Webhook: Status change notice attempts

    E ->>+ L: Status Notice(POST HTTPS);
    L -->>- E: Interrupted communication;   
    E ->>+ E: Waiting x minutes
    E ->>+ L: Status Notice (POST HTTPS);
    L -->>- E: HTTP 200 Status-Code:OK;

    Note over L, E: Webhook: Unsuccessful Status change notice attempts

    E ->>+ L: Status Notice(POST HTTPS);
    L -->>- E: Interrupted communication;   
    E ->>+ E: Waiting x minutes
    E ->>+ L: Status Notice (POST HTTPS);
    L -->>- E: Interrupted communication;
    E ->>+ E: Transaction = Pending Notice;

    Note over L, E: Status Cancellation

    L->>+ E: GET https://<carat url>/e-sitef/v2/transactions/{nit}
    E -->>- L: json with cancellation data informing status

Status API Omnipay vs Tratamento & Retorno