Life cycle and Errors

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:

Status	Description
CREATED	Initial Bulk status
TOP_UP_STARTED	A 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_PROGRESS	The payment intent was confirmed and the top up is in progress (waiting for the funds to be available)
PAYMENT_IN_PROGRESS	Money is inside the smart account and the payment requests are being processed
ERROR	Or all payments failed or the top up failed
PARTIALLY_COMPLETED	Some payments were successful and some failed
COMPLETED	All 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.