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:
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.
Updated 2 months ago