SimPayDocs

    Chargeback API

    Return money received through PIX, in full or in part, and follow the outcome

    Chargeback API

    The Chargeback endpoints let you return money you received through PIX, in full or in part, and follow the outcome. They cover both cash in flows: payments received through a QR Code you generated, and PIX transfers received on your PIX key or on your branch and account number.

    Which Endpoint to Use

    There are two ways to point at the payment you want to refund. Pick the one that matches what your system stored.

    What you haveRequest the refund withCheck the status with
    QR Code IDPOST /v2/finance/chargebacks-pix-copy-and-pasteGET /v2/finance/chargebacks-pix-copy-and-paste/status
    Cash in transaction IDPOST /v2/finance/chargebackGET /v2/finance/chargeback/status

    The cash in transaction route accepts any PIX cash in you received, including payments that originally came from a QR Code. The QR Code route only accepts payments made against a QR Code you generated.

    If you only have the EndToEndId, call GET /v2/finance/cashin/{e2e} first to get the cash in transaction ID.

    Available Endpoints

    • Request a Chargeback by QR Code - Refund a payment using the QR Code ID
    • Check Chargeback Status by QR Code - Query the refund by chargeback ID or EndToEndId
    • Request a Chargeback by Cash In Transaction - Refund any received PIX using the cash in transaction ID
    • Check Chargeback Status by Cash In Transaction - Query the refund by chargeback ID

    Chargeback Process

    1. Identify the payment to be refunded (QR Code ID, or cash in ID from GET /v2/finance/cashin/{e2e})
    2. Submit the refund request with the amount and the reason
    3. Refund is settled - immediately when the payer's account is in the same institution, asynchronously otherwise
    4. Track the status until it reaches SUCCESS or REJECTED
    5. A webhook is delivered when the refund completes

    Refund Amounts

    • Full - amount equals the value received
    • Partial - amount is lower than the value received
    • Multiple - several partial refunds are allowed while their sum does not exceed the value received

    Status Values

    StatusDescription
    PENDINGRefund accepted and being settled
    SUCCESSRefund completed and money returned to the payer
    REJECTEDRefund could not be completed

    Refunds of payments received from the same institution are settled immediately and already come back as SUCCESS. Everything else starts as PENDING.

    Use Cases

    • Order cancellations and customer refunds
    • Returning a payment received in error
    • Partial refunds when only part of an order is returned
    • Resolving disputed charges

    Limitations

    • Refunds are accepted for up to 90 days after the payment was received
    • The sum of all refunds cannot exceed the original amount
    • Only one refund can be in processing at a time for the same payment
    • The account must have enough available balance at the moment of the request
    • Closed accounts cannot send or receive a refund

    Webhooks

    EventTrigger
    QR_CODE_COPY_AND_PASTE_REFUNDEDRefund of a QR Code payment completed
    QR_CODE_COPY_AND_PASTE_REFUNDED_ERRORRefund of a QR Code payment failed
    PIX_CASHIN_REFUNDEDRefund of a received PIX transfer completed
    PIX_CASHIN_REFUNDED_ERRORRefund of a received PIX transfer failed

    Best Practices

    • Use webhooks instead of polling the status endpoint
    • Always send a descriptive information field - it helps support and reconciliation
    • Store the returned chargeback id for later status queries
    • Check how much was already refunded before requesting a new partial refund
    • Expect PENDING and handle it: do not treat a non-SUCCESS first response as a failure