Life cycle and Errors

Bulk payments will move through states from the top up payment its done, until the last payment requests its completed.

Status life cycle

To understand the current status of a bulk payment, you must review the status field from the bulk.

It can be one of the following ones:

StatusDescription
CREATEDInitial Bulk status
TOP_UP_STARTEDA payment intent was created to top up the smart account
WAITING_PAYER_AUTHORIZATION(this is just for Payment Initiation) when the payer needs to authorize the payment
TOP_UP_IN_PROGRESSThe payment intent was confirmed and the top up is in progress (waiting for the funds to be available)
PAYMENT_IN_PROGRESSMoney is inside the smart account and the payment requests are being processed
ERROROr all payments failed or the top up failed
PARTIALLY_COMPLETEDSome payments were successful and some failed
COMPLETEDAll payments were successful

Here is an representation of how the status are related between:

Refunds

When one of the Payment Request encounters a definitive error, that can't be retried, we prepare this payment to be refunded. The refund process is done automatically on error, so the user always holds his available balance.

When the payment fails it changes to, it will be refunded to the debtor's account. For example, if you have a bulk payment with 2 payment requests and one fails, this will be the scenario:

{
    "id": "e6b6974b-e790-4dae-9826-c26e30e2cb5e",
    "status": "PARTIALLY_COMPLETED",
    "totalAmount": 302,
    "feesAmount": 2,
    "grossAmount": 200,
    "paymentRequests": [
        {
            "id": "6ab34b81-625a-43ae-a1c6-aafa790aecb5",
            "amount": 200,
            "description": "Payment with error",
            "status": "REFUNDED",
            "createdAt": "2024-06-14T14:44:07.059Z",
            "updatedAt": "2024-06-14T14:45:53.096Z",
            "callbackUrls": null,
            "bulkPaymentId": null,
            "recipient": null,
            "clientPaymentId": null,
            "customer": null,
            "fees": 1,
            "pixQrCode": null,
            "boleto": null,
            "smartAccount": null,
            "schedule": null
        },
        {
            "id": "1709feb4-3658-4685-97b3-cb3b87343ef8",
            "amount": 100,
            "description": "Payment success",
            "status": "COMPLETED",
            "createdAt": "2024-06-14T14:44:47.294Z",
            "updatedAt": "2024-06-14T14:45:46.932Z",
            "callbackUrls": null,
            "bulkPaymentId": null,
            "recipient": null,
            "clientPaymentId": null,
            "customer": null,
            "fees": 1,
            "pixQrCode": null,
            "boleto": null,
            "smartAccount": null,
            "schedule": null
        }
    ]
}

In this case, the first Payment Request will be refunded (amount + fees), in this case by R$ 201.00.