Arcorapay

Migration · v0.9 → v0.10

How to move from v0.9 to v0.10 — the custody escrow gateway.

The custody-escrow gateway is canonical since 2026-05-07. The current live deployment isArcFXGateway at 0x07BAC123…aE3a3 (recorded in packages/contracts/deployments/arc-testnet.json). All earlier deployments (v0.6 — v1.1) remain on-chain (immutable) but are no longer watched — testnet was wiped on 2026-05-20. The escrow-model change documented below was the v0.9 → v0.10 migration.

What changed

v0.9v0.10
Settlement targetFunds delivered directly to merchants[m].payoutAddressFunds held in per-invoice escrow inside the gateway
Refund mechanismPulled from payments[].payoutSource via ERC-20 allowanceDrained from gateway escrow — no allowance dance
Refund windowIndefinite (as long as merchant pre-approves)7 days from settle (escrow drains on claim)
Fee accrualAt settleAt claim — refunded invoices earn no protocol fee
Merchant claimn/a (auto-paid at settle)Permissionless claim(globalIds[]) after the 7-day window
Delegate authorizationauthorizeDelegate(delegate, expiresAt)authorizeDelegate(delegate, expiresAt, rights) with bit-flag scope (RIGHT_CREATE_INVOICE | RIGHT_REFUND)
ReactivationImplicit (deactivated merchants could re-register)Admin-only reactivateMerchant(addr)
Fee boundOff-chain only (deploy script require)In-constructor require(feeBps <= 1000)

Migration steps

Merchants on the hosted checkout

  1. Visit /m/dashboard → click Activate gateway → on the activation card. Sign one registerMerchant(payoutAddress, payoutToken) tx.
  2. Visit /m/settings → On-chain authorization →Authorize delegate. Sign oneauthorizeDelegate(serverWallet, MAX_UINT64, RIGHT_CREATE_INVOICE) tx.
  3. You're done. New invoices route to v0.10 automatically.

SDK users

const arcora = new Arcora({
  apiKey: process.env.ARCORA_API_KEY,
});
// no engine arg — /api/invoices is v0.10-only

The SDK signature is unchanged; the legacy ?engine= query param is gone. v0.10's ABI matches v0.9 for the client-side Permit2 flow, so no checkout changes are needed.

Webhooks

Payload shape unchanged. Two new event types ship with v0.10:

  • invoice.claimed — fires when the gateway releases the merchant's leg from escrow (after the 7-day window).
  • invoice.recovered — fires when admin sweeps escrow from a deactivated merchant after the 14-day floor.

The 7-day window in practice

After settle, the merchant's portion sits in gateway custody for 7 days before becoming claimable. During that window refundInvoice(globalId) drains the full escrow back to the customer with no on-chain time check — the "window" is enforced indirectly: once anyone calls claim(), the escrow is gone and refunds revert withInvoiceNotRefundable. So in practice merchants have until the first claim()runs to issue a refund. Late chargebacks beyond that need off-chain settlement.

Migration · v0.9 → v0.10 · Arcorapay docs