Skip to main content

Cash-in Status Flow

We will show the life cycle for PIX payins, regarding the status. The notification sent to the payin will be based on the final status. The final status represents when the payment is completed, approved by compliance, and with the value available for withdrawal.
Charges (payin) in final statuses (CREATED, CANCELED, REJECTED) can no longer be updated.
The status will follow the cycle below:

Cash-in pix

PIX notifications will be completed shortly after the payment is done.

PIX Status Flow Explanation

  1. CREATED: Initial status when the payin is created
  2. CANCELED: Canceled by operator or expired
  3. PAID: Payment paid
  4. CREDITED: Payment credited, final status
  5. REJECTED: Blocked by compliance review

Cash-in boleto

Payments made by boleto do not undergo compliance validation after payment, as it is not possible to automatically refund this form of payment.Boleto notifications will be cleared after 1 working days.
Note: refunds done to customers must be done apart the api

Boleto Status Flow Explanation

  1. CREATED: Initial status when the payin is created
  2. CANCELED: Canceled by operator or expired
  3. PAID: Payment paid
  4. CREDITED: Payment credited, final status
  5. DROP_REQUESTED: Cancellation requested (when boleto expires)
  6. REJECTED: Blocked by compliance review

Possible charge (payin) status

ENUM_CODESTATUSEXPLANATION
1CreatedThe first status when the payin is created
2CanceledCash-in canceled due to expiration
3PaidCash-in successfully paid
4CreditedThe amount is paid and available for withdrawal / settlement
5Drop_requestedCash-in transaction canceled at the user’s request
7RejectedCash-in rejected due to compliance reason

Status Details

Initial StatusThis is the first status when a payin is created. The charge is active and waiting for payment.
  • PIX: QR Code is generated and ready to be scanned
  • Boleto: Boleto is generated and ready to be paid
Next possible statuses: Paid, Canceled, Drop_requested
Final StatusCash-in was canceled due to expiration or operator action.Reasons:
  • Expiration date reached without payment
  • Manual cancellation by operator
  • Automatic cancellation after drop_requested
Action: No further action possible. Create a new charge if needed.
Intermediate StatusPayment was successfully received but is under compliance review.
  • PIX: Payment confirmed in seconds
  • Boleto: Payment confirmed after bank processing (D+1)
Next possible statuses: Credited, Rejected
Final StatusThe amount is paid, approved by compliance, and available for withdrawal/settlement.This is the final success status:
  • Funds are available in your wallet
  • Webhook notification is sent
  • Ready for withdrawal or settlement
Action: Funds can now be withdrawn or used for payouts.
Intermediate StatusCash-in transaction cancellation was requested.
  • PIX: Canceled immediately
  • Boleto: Enters cancellation queue, takes 1 working day
Next status: Canceled
Final StatusCash-in was rejected due to compliance validation.Reasons:
  • Failed compliance checks
  • Document restrictions
  • Blocked by fraud prevention
Action: Review rejection reason and create new charge with corrected information.See Rejection Reasons for more details.

Webhook Notifications

Webhooks are sent only for final statuses: Credited, Canceled, Rejected

When to Expect Webhooks

  • PIX
  • Boleto
Fast NotificationsPIX webhooks are sent shortly after payment completion:
  • Credited: Within seconds after payment approval
  • Rejected: Within seconds if compliance fails
  • Canceled: Immediately after cancellation
{
  "id": 32457,
  "invoice": "YOUR-CODE1234",
  "status": {
    "id": 5,
    "name": "Credited"
  },
  "updated_at": "2024-06-12T23:04:27.000000Z"
}

Status Monitoring

1

Create Charge

Use Create Charge to generate a PIX or Boleto.Initial status: Created (1)
2

Customer Pays

Customer completes payment using PIX QR Code or Boleto.Status changes to: Paid (4)
3

Compliance Check

System performs compliance validation (PIX only).
  • If approved: Credited (5)
  • If rejected: Rejected (3)
4

Receive Webhook

Webhook notification is sent with final status.Your system receives the notification and processes accordingly.

Best Practices

Implement Webhooks

Always use webhooks instead of polling to receive status updates efficiently.

Handle All Statuses

Implement logic to handle all possible statuses in your application.

Check Final Status

Only consider Credited (5) as successful payment. Paid (4) is still under review.

Monitor Expiration

Set appropriate expiration dates and handle Canceled status gracefully.

Integration Example

// Webhook handler for payin status updates
app.post('/webhook/payin', async (req, res) => {
  const { id, invoice, status, updated_at } = req.body;
  
  console.log(`Received webhook for charge ${id}`);
  console.log(`Invoice: ${invoice}`);
  console.log(`Status: ${status.name} (${status.id})`);
  
  switch (status.id) {
    case 5: // Credited
      console.log('✓ Payment successful and credited');
      await processSuccessfulPayment(id, invoice);
      break;
      
    case 3: // Rejected
      console.log('✗ Payment rejected by compliance');
      await handleRejectedPayment(id, invoice);
      break;
      
    case 2: // Canceled
      console.log('⊘ Payment canceled or expired');
      await handleCanceledPayment(id, invoice);
      break;
      
    default:
      console.log(`Unexpected status: ${status.name}`);
  }
  
  // Always respond 200 OK to acknowledge webhook receipt
  res.status(200).json({ received: true });
});

async function processSuccessfulPayment(chargeId, invoice) {
  // Update order status
  await updateOrderStatus(invoice, 'paid');
  
  // Send confirmation email
  await sendConfirmationEmail(invoice);
  
  // Trigger fulfillment
  await triggerFulfillment(invoice);
}

async function handleRejectedPayment(chargeId, invoice) {
  // Get rejection reason
  const charge = await getCharge(chargeId);
  const rejectionReason = charge.substatus?.name;
  
  // Notify customer
  await notifyCustomer(invoice, 'rejected', rejectionReason);
  
  // Update order status
  await updateOrderStatus(invoice, 'payment_failed');
}

async function handleCanceledPayment(chargeId, invoice) {
  // Update order status
  await updateOrderStatus(invoice, 'canceled');
  
  // Notify customer
  await notifyCustomer(invoice, 'canceled');
}

Additional Notes

You can check the reasons why our compliance team will reject a payment in our article Rejection reasons payin.
For more information about webhook, check our article Webhook Signature Documentation.