Status Webhook

Status Machine:

Waiting

Success

Failed

Status Detailed

ENQUEUED (Payment Initiation enqueued);

CONSENT_AWAITING_AUTHORIZATION (Awaiting user authorization for consent);

CONSENT_AUTHORIZED (Consent authorized by user);

PAYMENT_PENDING (Consent consumed and Payment transaction is pending);

PAYMENT_SETTLEMENT_PROCESSING (Payment initiation accepted and payment processing started);

PAYMENT_SETTLEMENT_DEBTOR_ACCOUNT (Debt made to the payer's account);

PAYMENT_COMPLETED (Credit made at the destination account);

EXPIRED (Payment expired before is consent created);

CONSENT_REJECTED (Payment rejected by user or consent expired);

PAYMENT_REJECTED (Payment instruction rejected);

ERROR (Validation failure or process error);

CANCELED (Canceled by any other means).

Payment status can be returned via webhook. This way, when creating the transaction, we send a request with the redirection URL.

After the conclusion of the operation by the user, we send the final status of the transaction.

Example of webhooks

{
    "callbackId": "0796dba6-0883-4fb6-b718-bc74288f9443",
    "callbackStatus": "created",
    "eventType": "pix_direct_success",
    "customerId": "01934f01-f6db-7cc7-a269-ca4976520386",
    "pixDirectPayment": {
        "paymentId": "8a4300bd-d349-4d50-8289-416eee069b4e",
        "paymentStatus": "success",
        "paymentStatusDetailed": "PAYMENT_COMPLETED",
        "createdAt": "2025-10-09T19:54:31.293Z",
        "updatedAt": "2025-10-09T19:54:36.718Z",
        "paymentDate": "2025-10-09T00:00:00.000Z",
        "payerInformation": {
            "taxId": "02427606006",
            "name": "Andre"
        },
        "pixAccountInfos": {
            "personType": "CNPJ"
        },
        "participant": {
            "participantId": "0b919e9b-bee0-4549-baa3-bb6d003575ce",
            "name": "Banco de Testes do Iniciador",
            "avatar": "https://storage.googleapis.com/inic-data/iniciador-mock-bank.svg"
        },
        "additionalInformation": [
            {
                "name": "1312312",
                "content": "1132312"
            }
        ],
        "amount": 1,
        "customerId": "01934f01-f6db-7cc7-a269-ca4976520386",
        "endToEndId": "E44471172202510091954U278aa6651d",
        "externalId": "1fdc16a4-1289-4d57-979c-fa2ded8735d7"
    }
}

{
    "callbackId": "f4869eae-7a56-4ab6-9bc9-5dc0e3d761f8",
    "callbackStatus": "created",
    "eventType": "pix_direct_failed",
    "customerId": "01934f01-f6db-7cc7-a269-ca4976520386",
    "pixDirectPayment": {
        "paymentId": "39b31f18-9b76-4e1d-a951-3facc4a629f2",
        "paymentStatus": "failed",
        "paymentStatusDetailed": "PAYMENT_REJECTED",
        "failedReason": "Saldo insuficiente",
        "failedDescription": "The selected account does not have enough funds to make the payment.",
        "createdAt": "2025-10-09T20:31:22.110Z",
        "updatedAt": "2025-10-09T20:31:22.288Z",
        "paymentDate": "2025-10-09T00:00:00.000Z",
        "payerInformation": {
            "taxId": "02427606006",
            "name": "Andre"
        },
        "pixAccountInfos": {
            "personType": "CNPJ"
        },
        "participant": {
            "participantId": "0b919e9b-bee0-4549-baa3-bb6d003575ce",
            "name": "Banco de Testes do Iniciador",
            "avatar": "https://storage.googleapis.com/inic-data/iniciador-mock-bank.svg"
        },
        "additionalInformation": [
            {
                "name": "1312312",
                "content": "1132312"
            }
        ],
        "amount": 242204,
        "customerId": "01934f01-f6db-7cc7-a269-ca4976520386",
        "endToEndId": "E44471172202510092031U2c858fa201",
        "externalId": "d6a9a61a-ab57-43ae-98bf-269c2eb23f47"
    }
}

Possible errors:

Error (OKTO)	Description
INVALID_PAYMENT_DETAIL	Invalid payment detail.
PARAMETER_NOT_PROVIDED	Parameter not provided.
INVALID_PARAMETER	Invalid parameter.
IDEMPOTENCY_ERROR	Idempotency error.
NOT_PROVIDED	Not informed.
INVALID_VALUE	The amount sent is not valid for the provided QR Code.
INFRASTRUCTURE_FAILURE	Description of the infrastructure failure that prevented processing.
AUTHORIZATION_EXPIRED	Consent expired before the user could confirm it.
USER_REJECTED	The user rejected the consent authorization.
ACCOUNT_NOT_ALLOWED_FOR_PAYMENT	The selected account type [salary/investment/settlement/other] does not allow this payment.
INSUFFICIENT_FUNDS	The selected account does not have enough funds to make the payment.
AMOUNT_EXCEEDS_LIMIT	The amount exceeds the limit set [by the institution/arrangement/other] for transactions.
CONSENT_ATTEMPTS_LIMIT_REACHED	The maximum number of attempts to create the consent has been reached.
UNKNOWN_ERROR	An unidentified error occurred in the initiator or account holder.
INVALID_PAYMENT_DETAIL	Invalid payment detail.
PAYMENT_REJECTED_BY_HOLDER	Payment rejected by the account holder’s institution.
PAYMENT_REJECTED_BY_SPI	Payment rejected by the Instant Payment System (SPI).
INFRASTRUCTURE_FAILURE	Description of the infrastructure failure that prevented processing.
INFRASTRUCTURE_FAILURE_SPI	Failure in the Instant Payment System (SPI).
INFRASTRUCTURE_FAILURE_ICP	Failure in the Public Key Infrastructure (ICP).
INFRASTRUCTURE_FAILURE_RECEIVING_PSP	Failure in the infrastructure of the Payment Service Provider (PSP) receiving the payment.
INFRASTRUCTURE_FAILURE_HOLDER	Failure in the infrastructure of the account holder’s institution.