Payments

Payments represent charge attempts associated with invoices. Each payment tracks the status, method, gateway used, and provider response.

Payment Statuses

pending → processing → succeeded → refunded
             ↓             ↓
           failed    partially_refunded
             ↓
          canceled

Status	Description
pending	Awaiting processing
processing	Sent to gateway, awaiting response
succeeded	Confirmed as paid
failed	Declined by gateway or error
canceled	Manually canceled
partial	Partial payment received
refunded	Fully refunded
partially_refunded	Partially refunded

Payment Flow

1. Automatic Charge (charge_automatically)

Invoice finalized
  → Applies credits automatically
  → If credits cover everything: invoice = paid
  → If not:
    → Gets default payment method
    → Processes payment via gateway
    → Card: immediate response
    → Boleto/PIX: awaits gateway webhook
  → Success: invoice = paid
  → Failure: schedules retry (dunning)

2. Manual Payment

The operator or customer initiates payment via the dashboard or portal.

Processing a Payment

When processing, the system:

1. Validates that the invoice is open
2. Determines the payment method (provided, saved, or default)
3. Gets the organization's gateway for the payment type
4. Creates a payment record with an idempotency key
5. Sends the charge to the gateway
6. Updates the payment with the response

Idempotency

Each payment has a unique idempotency key. Duplicate requests return the existing result without reprocessing.

Special Scenarios

Partial Payment

• The received amount is less than the total
• The invoice remains open with the balance updated
• The customer can pay the remaining amount with another payment

Overpayment

When the paid amount exceeds the invoice balance:

1. The invoice amount is applied normally
2. The surplus becomes a credit automatically on the customer's account
3. The credit is of type adjustment with description "Overpayment credit on invoice {number}"
4. The credit will be automatically applied to future invoices

Already Paid Invoice

If the invoice was already paid when the payment is processed, the full amount becomes a credit on the customer's account.

Operations

Cancel Payment

Only pending payments can be canceled. For boleto/PIX, the cancellation is sent to the gateway.

Refund

succeeded or partially_refunded payments can be refunded:

• Full refund: Status changes to refunded
• Partial refund: Status changes to partially_refunded
• The request is sent to the gateway when available

Retry

failed payments can be retried. A new payment is created with the same amount, invoice, and method.