Charging & Collecting Payment

How Payment Collection Works

ABAXUS collects payment by creating a charge through your configured payment provider (Stripe or Adyen). ABAXUS does not store payment card data — all sensitive payment information lives in Stripe or Adyen. ABAXUS holds a reference to the customer’s payment method ID in your provider and uses that reference when creating a charge.

When you call POST /v1/invoices/:id/charge, ABAXUS:

1. Looks up the customer’s default payment method from their ABAXUS record
2. Creates a PaymentIntent (Stripe) or initiates a payment (Adyen) for the invoice’s total_amount
3. Waits for the payment provider’s synchronous confirmation
4. Transitions the invoice to paid on success
5. Records the payment event in the invoice audit trail

POST /v1/invoices/:id/charge

1
2
3
4

curl -X POST "$ABAXUS_URL/v1/invoices/inv_01hx9kr2s3t4u5v6w7x8y9z0/charge" \
  -H "Authorization: Bearer $ABAXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response on success:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "invoice_id": "inv_01hx9kr2s3t4u5v6w7x8y9z0",
  "status": "paid",
  "amount_charged": 18749,
  "currency": "usd",
  "payment_provider": "stripe",
  "payment_intent_id": "pi_3Nx8kStripe123456",
  "payment_method_id": "pm_card_acme_visa",
  "charged_at": "2026-04-03T11:05:22Z"
}

Response on payment failure:

1
2
3
4
5
6
7
8
9

{
  "invoice_id": "inv_01hx9kr2s3t4u5v6w7x8y9z0",
  "status": "issued",
  "error": {
    "code": "card_declined",
    "message": "Your card was declined.",
    "payment_intent_id": "pi_3Nx8kStripe_failed"
  }
}

A failed charge does not change the invoice status — it remains issued and can be retried. ABAXUS does not perform automatic retries. If you need dunning (automated retry sequences), implement it in your billing operations code by scheduling retry calls against this endpoint.

Audit Trail

Every significant event in an invoice’s lifecycle is recorded and retrievable:

1
2

curl "$ABAXUS_URL/v1/invoices/inv_01hx9kr2s3t4u5v6w7x8y9z0/events" \
  -H "Authorization: Bearer $ABAXUS_KEY"

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

{
  "invoice_id": "inv_01hx9kr2s3t4u5v6w7x8y9z0",
  "events": [
    {
      "type": "invoice.created",
      "occurred_at": "2026-04-03T11:00:00Z",
      "actor": "api_key:sk_live_xxx",
      "data": { "total_amount": 18749 }
    },
    {
      "type": "invoice.charge_attempted",
      "occurred_at": "2026-04-03T11:05:20Z",
      "actor": "api_key:sk_live_xxx",
      "data": { "payment_intent_id": "pi_3Nx8kStripe123456" }
    },
    {
      "type": "invoice.paid",
      "occurred_at": "2026-04-03T11:05:22Z",
      "actor": "system",
      "data": { "payment_intent_id": "pi_3Nx8kStripe123456", "amount": 18749 }
    }
  ]
}

The audit trail is append-only and immutable. It records the actor (which API key triggered the action), the timestamp, and structured data about what happened. This is your compliance record for every billing action.

Sending Invoice Emails

To trigger an invoice email notification:

1
2
3
4
5
6
7

curl -X POST "$ABAXUS_URL/v1/invoices/inv_01hx9kr.../send-email" \
  -H "Authorization: Bearer $ABAXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "billing@acme.io",
    "cc": ["cfo@acme.io"]
  }'

ABAXUS generates the invoice content and triggers the email via your configured email provider. The actual delivery is handled by the email integration you’ve set up in Settings → Integrations.

Archiving Invoices

To close an invoice without charging (write-off, dispute resolution, zero-amount cleanup):

1
2
3
4
5
6
7

curl -X POST "$ABAXUS_URL/v1/invoices/inv_01hx9kr.../archive" \
  -H "Authorization: Bearer $ABAXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "write_off",
    "note": "Customer on annual contract — prepaid."
  }'

Archiving is recorded in the audit trail with the provided reason and note. Archived invoices remain visible in the invoice list and can be exported, but cannot be charged.

Invoice State Machine Summary

          created
             │
          issued ──── charge_attempted (failure) ──── issued (retry)
             │
             ├──── paid  (charge succeeded)
             │
             └──── archived  (manual close)

All transitions are logged in the invoice events trail. Once in paid or archived, an invoice is terminal and cannot transition to any other state.