Payments and treasury
Approved bills settle in USDC on Arc. The agent wallet is a Circle developer-controlled wallet. The vendor destination is an Arc address on the organization allowlist.
African bank Fund and Withdraw (PAJ) move live local currency — NGN, GHS, TZS, KES, ZAR — against the USDC agent when PAJ_API_KEY is set. That is separate from the older Nigeria file-export rail (nigeria_sandbox / nigeria_export), which still only writes a file unless NIGERIA_PAYMENT_LIVE=true.
Pay client on Home sends USDC from the agent to any allowlisted 0x address, once or on a weekly/monthly schedule, with no invoice. See Fund, withdraw, Pay client.
Task queues, Circle states, and reconcile are in Agent payments.
Wallets
| Role | Meaning |
|---|---|
agent | Pays vendors. Balance is USDC. |
treasury_external | Company treasury address used to fund the agent. It is allowlisted automatically when linked. |
Provision the agent from Pay → Wallets. With ARC_ALLOW_SIMULATED false, a simulated agent cannot pay. Provisioning replaces it with a Circle wallet on Arc.
The USDC contract is the deployment default, or ARC_USDC_TOKEN_ADDRESS when that variable is set.
Fund the agent in USDC from treasury, then sync from the wallet screen or custara wallets sync. The balance shown in the product decreases when a transfer is accepted. A later sync reconciles it with Circle. A sync will not raise the balance above a spend recorded in the last 15 minutes.
What must be true before Arc pay
- Organization payment mode is live
ARC_PAYMENTS_LIVE=trueandARC_CHAINset to the deployment network. A test network also requiresARC_ALLOW_LIVE_ON_TESTNET=true- Circle API key and entity secret are configured
- Invoice currency is
USDCorUSD, or a live FX quote exists for the bill currency (NGN → USDC via Circle CPN when enabled, otherwise Coinbase spot). Pay is refused if no live quote returns. - Vendor has an active
arc_usdcendpoint - That address is on the allowlist
- Invoice status is
approvedorpayment_queued - No hard risks remain
- Extraction confidence is at or above the policy floor
- Agent balance covers the vendor settlement plus the Custara fee and the daily spend cap is not exceeded
- For a person paying at or above the MFA threshold, authenticator enrollment and a valid code
Creating a vendor with arc_address through POST /api/v1/vendors or custara vendors create adds the address to the allowlist.
Autopay
Autopay is on for new and existing organizations unless an admin turns it off.
The worker selects invoices where:
- the organization has autopay enabled
- status is
approved recommendedPayDateis today or earlier- the vendor is not new
- no hard risk remains
It then creates a payment intent as the system actor. That path does not prompt for MFA.
Platform fee
The buyer pays extra. The vendor still receives the full residual, and Odoo write-back uses that residual only.
Default take is 75 bps (0.75%) of the USDC settlement, floor 0.10 USDC, no ceiling. Env: PLATFORM_FEE_BPS, PLATFORM_FEE_MIN_USDC, PLATFORM_FEE_ADDRESS (Custara treasury 0x).
At pay time there are two transfers: vendor amount, then fee. If the vendor transfer succeeds and the fee fails, the bill stays paid and the fee is retried. The vendor is not clawed back.
Explorer links follow ARC_CHAIN (explorer.testnet.arc.io vs arc.etherscan.io).
After pay
- A payment intent is stored with rail
arc_usdcand modelive, plusfeeAmount/feeBpswhen a treasury address is set. - An
arc_transferagent task sends USDC from the agent wallet to the vendor address, then a second transfer toPLATFORM_FEE_ADDRESS. - When Circle reports a terminal success, an
arc_reconciletask writes the settlement and sets the invoice toreconciled. - Webhooks
payment.intent_created,payment.failed, andinvoice.reconciledfire for endpoints subscribed to those events. Nigeria export also emitspayment.executed.
If Redis is down, the API request runs the transfer in process so a CLI or API pay still reaches Circle. Reconcile of an in-flight transfer still prefers the worker. A completed Circle transaction is reconciled before the HTTP call returns when the transfer is already terminal.
Failure and retry
A failed intent can be retried from the receipt. Retry sends a new Circle transfer. It does not reuse a burned Circle idempotency key. If the amount is at or above the MFA threshold, the acting user must already have MFA enrolled.
Environment gates
| Variable | Effect |
|---|---|
ARC_PAYMENTS_LIVE | Must be true for live mode to transfer |
ARC_CHAIN | Arc network for the deployment |
ARC_ALLOW_LIVE_ON_TESTNET | Required when ARC_CHAIN is a test network |
ARC_ALLOW_SIMULATED | false in production |
ARC_USDC_TOKEN_ADDRESS | USDC contract on Arc, when the deployment overrides the default |
PLATFORM_FEE_BPS | Buyer-paid fee in basis points (default 75) |
PLATFORM_FEE_MIN_USDC | Floor in USDC (default 0.10) |
PLATFORM_FEE_ADDRESS | Custara treasury 0x. Required before live mainnet pay |
CIRCLE_API_KEY, CIRCLE_ENTITY_SECRET | Developer-controlled wallets |
CIRCLE_WEBHOOK_SECRET | Verifies Circle webhooks in production |
PAJ_API_KEY | Live African bank Fund/Withdraw (NGN, GHS, TZS, KES, ZAR) |
PAJ_WEBHOOK_SECRET | Verifies POST /api/webhooks/paj |
NIGERIA_PAYMENT_LIVE | Leave false until the older Nigeria file-export partner is live |
API_PAY_STEPUP_SECRET | When set, API payments:initiate in live mode must send X-Custara-Step-Up |

