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:

Possible PIX Rejected Reasons

A summary of error codes and their descriptions that may occur when attempting pay with PIX in a Bulk Payment

Code	Description
AB03	Payment expired due to timeout.
AB09	Transação interrompida devido a erro no participante do usuário recebedor.
AB11	Processing time at the paying participant longer than the 34-second timeout.
AC03	Número da agência e/ou conta transacional do usuário recebedor inexistente ou inválido.
AC06	A conta transacional especificada encontra-se bloqueada.
AC07	Número da conta transacional encerrada no PSP do Recebedor.
AC14	Incorrect type for the specified transactional account. Example: transfer to salary account.
AG03	The transaction type is not supported/authorized on the specified transaction account. E.g. transfer to salary account.
AM02	Ordem de pagamento/devolução em valor superou o limite permitido para o tipo de conta transacional creditada.
AM09	Devolução de pagamento em valor superou o valor da ordem de pagamento instantâneo correspondente.
BE01	CPF/CNPJ do usuário recebedor não é consistente com o titular da conta transacional especificada.
BE17	QR Code rejected by the receiving user's participant.
CH11	CPF/CNPJ do usuário recebedor incorreto.
CH16	It is not possible to send Pix to a salary account.
DS04	Ordem rejeitada pelo PSP do Recebedor.
DS24	Ordem rejeitada por extrapolação do tempo decorrido entre o envio da pain.013 e o recebimento da pacs.008 correspondente pelo participante do usuário recebedor.
DS27	ISPB of the receiving participant does not exist.
DT02	Date/time of receipt by participant greater than date/time of sending by participant.
DT05	A transação extrapolou o prazo máximo para devolução de pagamento instantâneo regulamentado pelo arranjo Pix.
ED05	Erro no processamento do pagamento.
RR04	Ordem de pagamento em que o usuário pagador é sancionado por resolução do Conselho de Segurança das Nações Unidas (CSNU). Nos casos em que o usuário recebedor for o sancionado, a ordem de pagamento não deve ser rejeitada.
SL02	A transação original não está relacionada ao serviço de Saque Pix ou Pix Troco.

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.