Skip to main content
An invoice in Caratuva is a request to collect a specific amount from a specific buyer. Each invoice has its own lifecycle, its own audit trail, and its own hosted payment link. You can manage invoices two ways:
  • From the dashboard — covered in this guide. Caratuva is your invoice system of record.
  • From your ERP via API — see Payment intents. Your ERP keeps the invoice; Caratuva handles collection.
Both paths produce identical buyer experiences and identical webhook events. Pick whichever matches your operating model.

​
Lifecycle

draft → awaiting_approval → approved → awaiting_buyer
                                     → buyer_kyc_pending
                                     → buyer_kyc_approved
                                     → fx_quoted
                                     → on_ramp_pending
                                     → fiat_received
                                     → offramp_pending
                                     → settled
settled is the terminal success state. The terminal non-success states are expired, cancelled, and buyer_kyc_rejected. on_ramp_failed and offramp_failed are in-flight failures that can be retried rather than terminal. (This is a simplified view; a few intermediate/retry statuses are omitted.)

​
Creating an invoice

From the dashboard, go to Invoices and click New to open the create form.
  • Buyer — name, email, country. The email is where the payment-link invitation lands. Pick carefully; sending to the wrong address means restarting from a fresh invoice.
  • Currency — the buyer’s currency (USD, EUR, or BRL). Caratuva quotes the FX into BRL automatically when the buyer confirms.
  • Amount — what the buyer pays you. Two-decimal precision. **USD invoices must be at least US10.00∗∗—buyersfundbybanktransfer,whichhasaUS10.00** — buyers fund by bank transfer, which has a US10 minimum, so a smaller USD invoice can’t be paid online.
  • Due date (optional) — the invoice expires automatically if not paid by then.
  • Reference / external ID (optional) — your internal order number. Round-trips onto every webhook so your ERP can match.

​
Line items

Add as many line items as you like. Each carries a description, quantity, unit price, and subtotal. Line items render verbatim on the buyer’s payment page — they’re for the buyer’s clarity, not for tax classification (Caratuva doesn’t validate NCM, HS, or origin codes here).

​
Export details (optional)

The form also collects export-specific fields when relevant: DU-E number, export contract reference, incoterm, and port of loading. These help your own records and reconciliation. (A free-text buyer-facing “notes” block exists only on the API payment-intents surface, not on this dashboard form.)

​
Save

Saving puts the invoice into draft. From here you can edit freely. Once you’re happy, click Submit for approval.

​
Approval (four-eyes)

Caratuva supports a four-eyes rule for larger disbursements. Your organization can set an approval threshold: any invoice whose amount meets or exceeds it is created in awaiting_approval, and the teammate who created it cannot approve it — a different teammate must. Invoices below the threshold (or any invoice if no threshold is set) go straight to draft and can be approved by the same person who created them. It’s a deliberate compliance control, focused where the amounts are large enough to matter. When an invoice needs approval:
  1. The invoice is created in awaiting_approval instead of draft.
  2. Your other teammates are notified that an invoice is waiting.
  3. A teammate other than the creator opens the invoice, reviews, and either approves or rejects.
  4. Approval transitions the invoice to approved. Rejection transitions it to cancelled and records the reason.
If your team is small, add a second teammate so above-threshold invoices have a separate approver — the creator can’t approve their own. Above-threshold invoices must be created from the dashboard by a person, not via an API key.

​
Inviting the buyer

Once approved, click Invite buyer. Caratuva emails the buyer a magic-link to the hosted payment page on pay.caratuva.com. The invoice transitions to awaiting_buyer. You can also:
  • Copy the link — share it through your own channel (CRM, ERP, WhatsApp, etc.). The link is unguessable but not secret-bearing on its own — sign-in still requires the buyer’s email.
  • Re-send the invitation — for buyers who lost the original email. There is a per-buyer-email rate limit to prevent inbox flooding.
See Payment links for what the buyer sees from here.

​
Watching settlement

The invoice detail page shows a live timeline of every state transition with a timestamp. The same events are also delivered as outbound webhooks; see Webhooks. Two states matter most for ops:
  • settled — funds have landed in your registered Brazilian bank account via PIX. Mark the order paid in your downstream systems.
  • buyer_kyc_rejected — terminal: the buyer failed identity verification. In-flight failures on_ramp_failed and offramp_failed are retryable rather than terminal; the detail page shows the exact reason in each case.

​
Cancelling an invoice

You can cancel an invoice up to and including fx_quoted — that is, any time before the buyer funds the on-ramp. From on_ramp_pending onward the buyer’s payment is already in flight and the invoice can no longer be cancelled; any reversal then happens through your downstream systems. Cancellation requires a reason (free-text). The buyer is automatically notified that the invoice is no longer payable.

​
Editing after creation

An invoice stays editable while it’s in draft or awaiting_approval. It becomes immutable once approved — the invoice you approve is the invoice the buyer pays. If the buyer or amount is wrong after approval, cancel and create a new one. (You can also use Reassign buyer from the detail page to move an invoice to a different buyer when a KYC flow is stuck.)

​
Bulk operations

Bulk creation is API-only — see Payment intents. The dashboard list view does not currently offer bulk export.

​
Tips

  • Use the reference / external ID field. Even if you operate primarily from the dashboard, a stable external ID makes it trivial to reconcile against your accounting system later.
  • Set due dates aggressively. A 7-day due date keeps your AR clean and makes follow-up automatic.
  • Test in test mode first. A new buyer in test mode lets you walk the entire flow yourself and learn what your buyers will see.