101pay Documents

Merchant onboarding

Start with an account, email verification, and dashboard access. Production use requires the relevant KYC and partner setup before live settlement.

• Register from the public site, verify email, then sign in to the merchant dashboard.
• Open Key management for payment key pairs and keep private keys server-side only.
• Use the dashboard to review transactions, platform bindings, funding records, and account security.
• When entering from Fluere SSO, set a 101pay password in Account security so the account can be managed directly later.

Authentication and API keys

101pay uses different credentials for different surfaces. Keep them separated so a checkout key is not reused as a user session.

• Key pair: public key plus private key for server-side charge requests.
• Session token: JWT from login, used for merchant management endpoints.
• Merchant API key: bearer key for selected x402 and payment-history endpoints.
• Staff and reviewer routes require role-scoped sign-in and must not be accessed with merchant credentials.

curl -X POST https://pay101-api-5qjldqffdq-uw.a.run.app/v1/auth/login \
  -H "content-type: application/json" \
  -d '{"email":"merchant@example.com","password":"***"}'

Checkout and payment sessions

Hosted checkout creates a payment session and returns a URL. The customer pays on the hosted page while 101pay tracks provider status and settlement evidence.

• Create a session with amount, currency, description, and optional business metadata.
• Send the hosted checkout URL to the customer or embed it in your payment flow.
• The hosted page handles method selection, payment instructions, confirmation, and status polling.
• Production confirmation should be driven by provider/webhook evidence instead of manual UI assumptions.

curl -X POST https://pay101-api-5qjldqffdq-uw.a.run.app/v1/checkout/sessions \
  -H "authorization: Bearer <JWT>" \
  -H "content-type: application/json" \
  -d '{"amount":"1500","currency":"USD","description":"Pro plan"}'

Agentic payments with x402

x402 lets an API price a resource with HTTP 402. An agent signs the payment authorization and retries the same resource request with X-PAYMENT.

• A resource without X-PAYMENT returns 402 Payment Required with payment requirements.
• The agent signs the required payment payload within its policy and budget.
• 101pay verifies and settles through the facilitator, then returns the paid resource.
• Use merchant payment history to reconcile agent spend by resource, customer, and request.

curl https://pay101-api-5qjldqffdq-uw.a.run.app/v1/resource/<sku>?merchant=<merchantId>
# 402 Payment Required -> agent signs -> retry with X-PAYMENT

Fluere binding and CRD funding

Fluere can bind a 101pay account so users can buy CRD, withdraw CRD, and track payout handoff from the 101pay side.

• A Fluere-linked 101pay account shows platform binding details in the dashboard.
• CRD purchase orders reserve 101pay funding balance and report status back to Fluere.
• CRD withdrawal orders originate in Fluere and use 101pay for payout destination and execution status.
• If the account is not linked, Fluere-specific funding panels stay hidden and the dashboard points users to platform bindings.

Funding wallets and deposits

Wallet records prove which customer-controlled address is allowed for deposit matching and payout records.

• MetaMask signing is the recommended browser flow; it signs a message only and does not create an on-chain transaction.
• Other wallets can sign the exact generated message and paste the signature manually.
• Deposits are matched by chain, source wallet, destination account, amount, transaction hash, and confirmation state.
• If a user sent funds before saving the wallet, saving the same address can allow pending deposit claim where eligible.

Withdrawals and payout modes

101pay records CRD withdrawal payout execution while Fluere remains the CRD ledger source of truth.

• Current default CRD withdrawal destination is USD bank account where enabled.
• USDC wallet records are retained for wallet payout fallback and audit history.
• Coinbase Business payout actions are staff-operated: open transfer, complete transfer externally, then record tx or payout evidence.
• Manual off-platform payouts should remain disabled history unless a staff exception explicitly requires them.

Staff and reviewer operations

Operational users review KYC, funding exceptions, treasury accounts, CRD purchase orders, withdrawal orders, deposits, payout batches, and ledger evidence.

• Reviewer routes focus on KYC review and partner transmission state.
• Staff Funding shows Fluere-linked accounts, wallet accounts, CRD purchase and withdrawal orders, deposits, payout batches, and ledger entries.
• Treasury surfaces public receiving accounts and operational balances used for deposit matching and exception handling.
• Every manual transition should leave status, note, operator, timestamp, and idempotency evidence.

Reference and errors

All API responses use JSON. Error bodies include a stable error code where possible so merchants and agents can recover deterministically.

• Common statuses: 400 invalid_request, 401 unauthorized, 402 payment_required or payment_rejected, 404 not_found, 409 conflict, 500 internal_error.
• Amounts use minor units in responses. USDC uses 6 decimals, USD uses 2 decimals, and JPY uses 0 decimals.
• Use idempotency keys or stable business references for retries, especially purchase, withdrawal, payout, and ledger operations.
• Production and staging may differ in OTP, provider mocks, and settlement rails. Always verify the target environment before testing funds.

{ "error": "key_pair_invalid", "message": "the public key and private key do not form a valid pair" }