# AGENTS
Source: https://docs.northfond.xyz/AGENTS
# NorthFond Mintlify documentation
* `docs.json` is the navigation and theme source of truth.
* Documentation pages are MDX files referenced from `docs.json`.
* Keep API behavior aligned with `../backend/src/routes/business/` and the canonical contract in `../B2B_API_README.md`.
* Run `npm run validate` before publishing.
* Never include real API keys, provider secrets, wallet mnemonics, or customer data in examples.
# CLAUDE
Source: https://docs.northfond.xyz/CLAUDE
@AGENTS.md
This project is hosted by Mintlify, not built or deployed as a Next.js application.
# PRODUCT
Source: https://docs.northfond.xyz/PRODUCT
# Product
## Register
brand
## Users
Backend engineers and product teams integrating stablecoin collection and local payouts into business software. They need exact contracts, safe sandbox workflows, and unambiguous production-readiness boundaries.
## Product Purpose
Help an approved business move from an API key to a verified NorthFond transaction with minimal guesswork. The documentation must explain the provider-neutral model, make the first request executable, and remain the trustworthy source for schemas, payment states, and operational behavior.
## Brand Personality
Calm, precise, and operational. NorthFond speaks like reliable financial infrastructure, not a speculative crypto product.
## Anti-references
Generic blue developer portals, neon crypto styling, vague feature marketing, undocumented examples, decorative dashboards, copied competitor language, and references that hide request or response contracts.
## Design Principles
1. Make the first successful request obvious.
2. Show exact contracts and examples instead of describing them abstractly.
3. State sandbox, live, chain, and route limitations beside the relevant action.
4. Keep provider complexity behind NorthFond's normalized resources.
5. Treat trust, security, retries, and reconciliation as core product content.
## Accessibility & Inclusion
Target WCAG 2.1 AA. Use descriptive links, a logical heading order, visible non-color status language, copyable examples, and concise prose that remains clear to developers working in a second language.
# API keys
Source: https://docs.northfond.xyz/api-keys
Create, scope, rotate, and revoke business credentials.
Create keys from the business dashboard for either sandbox or live. The raw secret is displayed once; NorthFond stores only its hash and display prefix.
Grant only the scopes your integration needs, such as `customers:read`, `customers:write`, `wallets:read`, `wallets:write`, `beneficiaries:read`, `beneficiaries:write`, `quotes:read`, `onramps:write`, `offramps:write`, and `transactions:read`.
Revocation is immediate. Deploy a replacement key and confirm successful traffic before revoking the old key.
# API reference overview
Source: https://docs.northfond.xyz/api-reference
Understand NorthFond API conventions before using the generated endpoint reference and interactive request builder.
Base URL: `https://payment.gideondevrel.xyz`
All `/api/v1/business/*` requests use a scoped bearer API key. Mutating requests require an `Idempotency-Key` unless an endpoint explicitly documents otherwise.
| Resource | Endpoints |
| ------------- | --------------------------------------------------------------------------- |
| Account | `GET /api/v1/business/account` |
| Customers | `POST/GET /api/v1/business/customers`, `GET /api/v1/business/customers/:id` |
| Wallets | `POST/GET /api/v1/business/wallets`, detail, balance, verification, archive |
| Beneficiaries | requirements, create, list, detail, update, archive |
| Quotes | `POST /api/v1/business/quotes`, `GET /api/v1/business/quotes/:id` |
| On-ramps | readiness and initiation |
| Off-ramps | initiation |
| Transactions | list, detail, settlement, confirmation, retry |
The endpoint pages in this section are generated from the repository's OpenAPI 3.1 contract. They include parameters, request and response schemas, and an interactive request builder.
Use sandbox credentials while integrating. A successful request with an `nf_live_` key can affect real funds when the requested route is enabled.
# Retrieve the authenticated business
Source: https://docs.northfond.xyz/api-reference/account/retrieve-the-authenticated-business
/openapi.json get /api/v1/business/account
# Archive a beneficiary
Source: https://docs.northfond.xyz/api-reference/beneficiaries/archive-a-beneficiary
/openapi.json delete /api/v1/business/beneficiaries/{id}
# Create an encrypted beneficiary
Source: https://docs.northfond.xyz/api-reference/beneficiaries/create-an-encrypted-beneficiary
/openapi.json post /api/v1/business/beneficiaries
# List beneficiaries
Source: https://docs.northfond.xyz/api-reference/beneficiaries/list-beneficiaries
/openapi.json get /api/v1/business/beneficiaries
# Load destination-specific beneficiary fields
Source: https://docs.northfond.xyz/api-reference/beneficiaries/load-destination-specific-beneficiary-fields
/openapi.json get /api/v1/business/beneficiaries/requirements
# Retrieve a beneficiary
Source: https://docs.northfond.xyz/api-reference/beneficiaries/retrieve-a-beneficiary
/openapi.json get /api/v1/business/beneficiaries/{id}
# Update a beneficiary label
Source: https://docs.northfond.xyz/api-reference/beneficiaries/update-a-beneficiary-label
/openapi.json patch /api/v1/business/beneficiaries/{id}
# Create a customer and managed wallet
Source: https://docs.northfond.xyz/api-reference/customers/create-a-customer-and-managed-wallet
/openapi.json post /api/v1/business/customers
Creates one reusable managed EVM wallet. Reusing the same external reference returns the existing customer.
# List customers
Source: https://docs.northfond.xyz/api-reference/customers/list-customers
/openapi.json get /api/v1/business/customers
# Retrieve a customer
Source: https://docs.northfond.xyz/api-reference/customers/retrieve-a-customer
/openapi.json get /api/v1/business/customers/{id}
# Initiate an off-ramp
Source: https://docs.northfond.xyz/api-reference/off-ramps/initiate-an-off-ramp
/openapi.json post /api/v1/business/offramps
Consumes an available quote and creates settlement instructions. Sandbox never moves funds or contacts a provider.
# List available off-ramp routes
Source: https://docs.northfond.xyz/api-reference/off-ramps/list-available-off-ramp-routes
/openapi.json get /api/v1/business/offramps/capabilities
Returns the provider-neutral countries, payout methods, chains, and business policy limits available to the authenticated environment.
# Check on-ramp environment readiness
Source: https://docs.northfond.xyz/api-reference/on-ramps/check-on-ramp-environment-readiness
/openapi.json get /api/v1/business/onramps/readiness
Returns configuration readiness without creating a quote, provider request, or payment.
# Initiate a managed-wallet on-ramp
Source: https://docs.northfond.xyz/api-reference/on-ramps/initiate-a-managed-wallet-on-ramp
/openapi.json post /api/v1/business/onramps
Consumes an on-ramp quote and simulates mobile-money collection and USDC delivery. Currently available only with sandbox credentials.
# Create an on-ramp or off-ramp quote
Source: https://docs.northfond.xyz/api-reference/quotes/create-an-on-ramp-or-off-ramp-quote
/openapi.json post /api/v1/business/quotes
# Retrieve a quote
Source: https://docs.northfond.xyz/api-reference/quotes/retrieve-a-quote
/openapi.json get /api/v1/business/quotes/{id}
# Attach and verify an EVM settlement transaction
Source: https://docs.northfond.xyz/api-reference/transactions/attach-and-verify-an-evm-settlement-transaction
/openapi.json post /api/v1/business/transactions/{id}/settlement/confirm
Sandbox accepts a simulated transaction hash. Live verifies the USDC contract, sender, receiver, exact amount, receipt, and confirmations.
# List transactions
Source: https://docs.northfond.xyz/api-reference/transactions/list-transactions
/openapi.json get /api/v1/business/transactions
Unlike `GET /v1/transaction_bundles`, this endpoint filters server-side, so you no longer need to page through every bundle to find a date range.
**Date range:** use `date_from`/`date_to` (transaction date) or `created_from`/`created_to` (record creation). Either bound is optional.
**Amount range:** `amount_min`/`amount_max` in cents.
**Statuses:** repeat `status_id` or comma-separate; IDs come from `GET /v1/transaction_statuses`.
Each transaction includes `contact_id`, so monthly metrics (unique donors, totals) can be computed directly.
# Retrieve a transaction and its status events
Source: https://docs.northfond.xyz/api-reference/transactions/retrieve-a-transaction-and-its-status-events
/openapi.json get /api/v1/business/transactions/{id}
# Retrieve settlement instructions
Source: https://docs.northfond.xyz/api-reference/transactions/retrieve-settlement-instructions
/openapi.json get /api/v1/business/transactions/{id}/settlement
# Retry managed-wallet settlement execution
Source: https://docs.northfond.xyz/api-reference/transactions/retry-managed-wallet-settlement-execution
/openapi.json post /api/v1/business/transactions/{id}/retry
Retries a managed-wallet transaction in action_required after the underlying operational issue has been corrected.
# Archive a wallet
Source: https://docs.northfond.xyz/api-reference/wallets/archive-a-wallet
/openapi.json delete /api/v1/business/wallets/{id}
# Create a wallet ownership challenge
Source: https://docs.northfond.xyz/api-reference/wallets/create-a-wallet-ownership-challenge
/openapi.json post /api/v1/business/wallets/{id}/verification-challenges
# List active wallets
Source: https://docs.northfond.xyz/api-reference/wallets/list-active-wallets
/openapi.json get /api/v1/business/wallets
# Read a wallet USDC balance
Source: https://docs.northfond.xyz/api-reference/wallets/read-a-wallet-usdc-balance
/openapi.json get /api/v1/business/wallets/{id}/balance
The chain query parameter is required for managed wallets. Sandbox returns a simulated balance; live reads canonical USDC on-chain.
# Register an external EVM wallet
Source: https://docs.northfond.xyz/api-reference/wallets/register-an-external-evm-wallet
/openapi.json post /api/v1/business/wallets
Managed wallets are created through the customer endpoint.
# Retrieve a wallet
Source: https://docs.northfond.xyz/api-reference/wallets/retrieve-a-wallet
/openapi.json get /api/v1/business/wallets/{id}
# Submit a wallet ownership signature
Source: https://docs.northfond.xyz/api-reference/wallets/submit-a-wallet-ownership-signature
/openapi.json post /api/v1/business/wallets/{id}/verify
# Beneficiaries
Source: https://docs.northfond.xyz/beneficiaries
Store reusable and encrypted local payout instructions.
First call `GET /api/v1/business/beneficiaries/requirements` with the destination currency and payment method. Render the returned required fields, collect the recipient details, then create the beneficiary with `POST /api/v1/business/beneficiaries`.
Sensitive payout details are encrypted at rest. List responses expose only redacted identifying information. Deleting a beneficiary archives it so historical transactions retain their references.
# Customers
Source: https://docs.northfond.xyz/customers
Represent your users and provision reusable managed wallets.
Customers are scoped to one business environment and identified by your stable `external_reference`. NorthFond does not add a second customer OTP flow: your application remains responsible for authenticating its users.
`POST /api/v1/business/customers` creates a customer. When managed wallets are enabled, NorthFond derives one reusable EVM address that works across supported EVM chains while balances remain chain-specific.
Use `GET /api/v1/business/customers` and `GET /api/v1/business/customers/:id` to retrieve customers.
# Errors
Source: https://docs.northfond.xyz/errors
Handle NorthFond API failures consistently.
Business API failures return a stable error code and human-readable message. Record the `X-Request-Id` response header and provide it to support.
```json theme={null}
{
"error": {
"code": "invalid_request",
"message": "The request body is invalid.",
"requestId": "2ea8064d-a6ef-49b4-8b7e-f27b57ca927c",
"details": {}
}
}
```
| Status | Meaning |
| ------ | ----------------------------------------------------------- |
| `400` | Invalid request or unsupported combination |
| `401` | Missing, malformed, expired, or revoked credential |
| `403` | Missing scope, blocked IP, disabled route, or policy denial |
| `404` | Resource not found in the authenticated tenant/environment |
| `409` | Idempotency conflict or invalid resource state |
| `422` | Valid shape but failed business validation |
| `429` | Rate or policy limit exceeded |
| `500` | Unexpected server error |
## Retry safely
Retry `429` and transient `5xx` responses with exponential backoff and jitter. Honor `Retry-After` when present and cap the number of attempts. Reuse the original `Idempotency-Key` for a retried write. Do not retry validation or authorization failures without changing the request or credential.
# Authentication
Source: https://docs.northfond.xyz/getting-started/authentication
Authenticate server-to-server requests with scoped bearer API keys.
NorthFond uses secret bearer credentials. Keep keys on your server and never place them in browser code, mobile applications, source control, screenshots, or logs.
```bash theme={null}
curl https://payment.gideondevrel.xyz/api/v1/business/account \
-H "Authorization: Bearer $NORTHFOND_API_KEY"
```
| Prefix | Environment | Money movement |
| ---------- | ----------- | ------------------------- |
| `nf_test_` | Sandbox | Simulated |
| `nf_live_` | Live | Real funds after approval |
## IP restrictions
Each key can allow up to ten exact IPv4 or IPv6 addresses. Requests from other addresses are rejected before endpoint processing.
## Rate limits
Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. Limited requests return `429` and a `Retry-After` header.
## Server environments
The API reference currently targets the public NorthFond backend at `https://payment.gideondevrel.xyz`. Sandbox and live access are separated by the credential prefix and the environment attached to the credential, not by putting a key in the URL.
# Make your first API request
Source: https://docs.northfond.xyz/getting-started/quickstart
Authenticate with a sandbox key and verify your NorthFond business environment in under five minutes.
This quickstart confirms that your server can authenticate with NorthFond. It does not move funds or create a payment.
## Before you begin
You need a NorthFond business account and a sandbox API key with at least one scope. Create the key in the [business dashboard](https://business.northfond.xyz/api-keys). The secret is shown once.
Keep API keys on your server. Never expose them in browser code, mobile applications, screenshots, logs, or source control.
Store the secret in your shell for this session.
```bash theme={null}
export NORTHFOND_API_KEY="nf_test_replace_with_your_key"
```
```bash theme={null}
curl --request GET \
--url https://payment.gideondevrel.xyz/api/v1/business/account \
--header "Authorization: Bearer $NORTHFOND_API_KEY"
```
A successful response identifies the business, environment, credential prefix, and granted scopes.
```json theme={null}
{
"id": "8d15d149-51a1-4b0e-a7e0-4a9ec5ea6970",
"name": "Acme Payments",
"environment": "sandbox",
"credential": {
"id": "7eafef9a-07cf-486a-91f1-c494190e6fd4",
"prefix": "nf_test_V2nJ64JC",
"scopes": ["customers:read", "customers:write"]
}
}
```
The current public sandbox origin is `https://payment.gideondevrel.xyz`. NorthFond will publish the production NorthFond-owned API hostname before general availability.
## Where to go next
Provision a reusable managed EVM wallet from your own customer reference.
Open the generated endpoint reference, schemas, and request builder.
## Common failures
| Response | Check |
| -------- | ---------------------------------------------------------- |
| `401` | The key is missing, malformed, expired, or revoked. |
| `403` | The key lacks permission or your source IP is not allowed. |
| `429` | Wait for `Retry-After`, then retry with backoff. |
# Idempotency
Source: https://docs.northfond.xyz/idempotency
Retry mutating requests without creating duplicate resources or payments.
Send a unique `Idempotency-Key` header on every mutating Business API request.
```bash theme={null}
curl -X POST https://payment.gideondevrel.xyz/api/v1/business/offramps \
-H "Authorization: Bearer $NORTHFOND_API_KEY" \
-H "Idempotency-Key: payout-order-8c7f" \
-H "Content-Type: application/json" \
--data @request.json
```
Repeating the same method, path, body, and key returns the stored response. Reusing a key for a different request returns a conflict. Generate keys from stable IDs in your own system and retain them across network retries.
# Stablecoin payments through one business API
Source: https://docs.northfond.xyz/introduction
Integrate provider-neutral wallets, quotes, on-ramps, off-ramps, transactions, and signed webhooks with NorthFond.
NorthFond lets approved businesses collect and disburse money across stablecoins and local payment methods. You integrate one normalized contract while NorthFond handles provider selection, settlement verification, and reconciliation.
Collect local currency and deliver USDC to a managed customer wallet.
Fund with USDC and pay a verified local beneficiary.
Provision managed EVM addresses or verify an external wallet.
Reconcile every normalized transaction state with signed events.
## The integration model
Use your own stable external reference. NorthFond provisions a reusable managed EVM address.
Collect the destination-specific payout details returned by the requirements endpoint.
Lock the exchange rate, fees, destination amount, route, and expiry.
Fund the transaction, persist its NorthFond ID, and follow normalized status changes through signed webhooks.
## Start integrating
Create a sandbox key and verify your account context.
Check environments, chains, and route boundaries before building.
Sandbox API keys start with `nf_test_` and never move real funds. Live keys start with `nf_live_`.
# Limits and policies
Source: https://docs.northfond.xyz/limits
Understand route permissions, transaction limits, and volume controls.
Policies are configured per business environment. They may restrict enabled directions, chains, currencies, payment methods, individual transaction amounts, and daily or monthly USDC-equivalent volume.
Usage enforcement is atomic and includes the candidate transaction. Transactions above a configured review threshold pause until an authorized administrator approves or rejects them.
# Dashboard notifications
Source: https://docs.northfond.xyz/notifications
Track payment lifecycle changes in the Business dashboard and by customer email.
The Business dashboard notification center reports payment review, processing, completion, and failure changes for the currently selected environment.
## Notification behavior
* Notifications are tenant- and environment-scoped.
* The unread counter represents all unread notifications, not only the currently loaded page.
* Older notifications load in pages of 20.
* **Mark all read** affects only the selected environment.
* Selecting a notification opens the related Payment Links workspace.
* A review-expiry reminder is created once per review.
## Customer emails
When a checkout contains a valid customer email address, NorthFond queues email for approval, rejection, completion, and terminal failure. Delivery happens outside the payment transaction and retries with backoff. An email-provider outage cannot roll back or duplicate a payment.
Customer email is a convenience notification. Your application should use signed webhooks and API/dashboard state as the system of record.
## Delivery states
Email and webhook deliveries are tracked as `pending`, `retrying`, `delivered`, or `failed`. NorthFond operators can see terminal failures and reviews approaching expiry in **Payment reviews**.
# Off-ramps
Source: https://docs.northfond.xyz/offramps
Convert USDC into supported local payout methods.
Start with `GET /api/v1/business/offramps/capabilities`. It returns the countries, currencies, payout methods, chains, and policy limits available to the authenticated business environment without exposing NorthFond's underlying providers.
After selecting a route, load its dynamic fields from `GET /api/v1/business/beneficiaries/requirements`, create or select a beneficiary, request an off-ramp quote, then call `POST /api/v1/business/offramps` with the quote and funding wallet. External-wallet flows return settlement instructions. Managed-wallet flows can execute from the customer's managed balance when enabled.
```bash theme={null}
curl https://payment.gideondevrel.xyz/api/v1/business/offramps/capabilities \
-H "Authorization: Bearer $NORTHFOND_API_KEY"
```
Capability results are specific to the API key's sandbox or live environment and its business policy. Refresh them instead of maintaining a static country list in your integration.
Live settlement verifies canonical USDC transfer logs, sender, recipients, exact amounts, receipt success, and required confirmations before provider submission.
The initial Business API scope is EVM-only. Base is the initial validation chain. Do not advertise Ethereum or Solana off-ramping until each has been explicitly enabled and validated.
See [supported capabilities](/platform/supported-capabilities) for the complete chain and environment boundary.
# On-ramps
Source: https://docs.northfond.xyz/onramps
Move local currency into a customer stablecoin wallet.
Check `GET /api/v1/business/onramps/readiness` before showing a live route. Create an on-ramp with `POST /api/v1/business/onramps` using the intended customer, wallet, amount, currency, and an idempotency key.
Sandbox on-ramps simulate payment and delivery. Live on-ramps validate immutable provider fields, reconcile provider status in the background, and emit transaction events and signed webhooks.
# Operational readiness
Source: https://docs.northfond.xyz/operational-readiness
Certify payment links, reviews, notifications, and webhooks before production.
## Staging checklist
1. Create and complete a normal sandbox M-Pesa checkout.
2. Verify exactly one confirmed treasury deposit and the expected treasury balance increase.
3. Replay completion and confirm it returns a conflict without changing settlement.
4. Create a review-required checkout and verify it appears in Payment Reviews.
5. Approve one review and reject another; confirm both decisions are audited.
6. Confirm business notifications and unread counts.
7. Confirm configured customer email delivery.
8. Confirm signed webhook delivery and replay behavior.
9. Confirm another tenant cannot read the payment intent.
10. Inspect Payment Reviews for failed email/webhook deliveries and expiring reviews.
## Automated checks
From the backend repository:
```bash theme={null}
export NORTHFOND_BASE_URL="https://your-staging-backend"
export NORTHFOND_API_KEY="nf_test_..."
export NORTHFOND_PAYMENT_PAGE_SLUG="your-sandbox-page"
npm run test:staging:business-payment-page
```
The canary creates simulated sandbox records but moves no funds. Set `NORTHFOND_OTHER_API_KEY` to a second sandbox tenant key to include the isolation probe.
To certify approval, rejection, merchant notifications, customer-email queuing, and operator health against a non-production live environment, use `npm run test:staging:business-payment-operations`. The script requires explicit `NORTHFOND_STAGING_REVIEW_CONFIRM=STAGING_ONLY` and refuses the known production hostname. It does not resume an approved payment or send an STK prompt unless `NORTHFOND_ALLOW_LIVE_PROMPT=SEND` is also set deliberately.
## Production rollout
Deploy migrations before enabling traffic, check `/health`, verify Payment Reviews operational health, then make one low-value live canary payment. Confirm the provider result, webhook, notification, customer email, treasury deposit, and ledger before increasing limits.
# Payment links
Source: https://docs.northfond.xyz/payment-links
Accept M-Pesa and USDC through a NorthFond-hosted checkout and settle into one business treasury.
Payment links let a business collect customer payments without creating a wallet for every customer or building a checkout UI. NorthFond hosts the payment page, tracks each payment as a payment intent, and credits the business treasury exactly once after completion.
## How it works
In the Business dashboard, open **Payment links** and choose currencies, payment methods, settlement mode, and optional amount boundaries.
Customers open `/pay/{slug}`, enter their details, amount, and preferred payment method.
Each submission creates a unique checkout URL and payment intent. Use the dashboard, notifications, or webhooks to follow its status.
Completed payments create one confirmed treasury deposit and one balanced ledger credit. Replays cannot credit the treasury twice.
## Settlement choices
| Mode | Customer pays | Business receives |
| ------------------------- | ---------------------- | ----------------------------------------------------------------- |
| Stablecoin settlement | M-Pesa or USDC | USDC in the NorthFond business treasury |
| Local-currency settlement | Supported local method | Local-currency settlement according to the business configuration |
Available methods and currencies are controlled by the business environment and payment-page configuration. Never hardcode the options shown to customers.
## Checkout states
`awaiting_payment` → `funds_detected` → `processing` → `completed`
A checkout can also become `review_required`, `approved`, `failed`, `cancelled`, or `expired`. Treat only `completed` as proof that settlement was finalized.
An `approved` checkout has permission to continue; it has not been paid. The customer must return and explicitly continue before NorthFond sends a new M-Pesa prompt.
## Reconciliation
Use the payment intent ID as the durable NorthFond identifier and your external reference as your internal order identifier. Confirm fulfillment from a signed `payment_intent.completed` webhook or by reading the payment in the Business dashboard. Do not fulfill from a browser redirect alone.
## Sandbox
Sandbox checkouts simulate payment and treasury credit without moving funds. Use sandbox to verify status handling, duplicate completion protection, tenant isolation, notifications, and webhook signatures before enabling live collection.
# Supported capabilities
Source: https://docs.northfond.xyz/platform/supported-capabilities
See which environments, chains, assets, directions, and payment methods NorthFond currently supports.
Use `GET /api/v1/business/offramps/capabilities` as the runtime capability boundary. It applies your environment's currency, payment-method, chain, country, transaction-limit, and manual-review policy. Do not maintain a static route list in production.
## Environments
| Capability | Sandbox | Live |
| -------------------------------- | --------- | ------------------------ |
| API authentication | Supported | Supported after approval |
| Deterministic payment simulation | Supported | Not applicable |
| Managed-wallet on-ramp | Supported | Readiness-gated |
| External-wallet off-ramp | Simulated | Readiness-gated |
| Managed-wallet off-ramp | Simulated | Disabled by default |
## Chains and assets
The initial Business API is EVM-only and uses canonical USDC.
| Chain | API identifier | Current status |
| --------- | -------------- | ----------------------------------------------- |
| Base | `base` | Initial validation chain |
| Polygon | `polygon` | Configuration-gated |
| Arbitrum | `arbitrum` | Configuration-gated |
| Optimism | `optimism` | Configuration-gated |
| Avalanche | `avalanche` | Configuration-gated |
| Ethereum | Not advertised | Requires separate end-to-end readiness approval |
| Solana | Not supported | Outside the initial B2B scope |
Do not assume a chain is live because its identifier is accepted by a schema. Check your environment policy and the applicable readiness endpoint before presenting a route to a customer.
## Local payment methods
Beneficiary requirements are dynamic. Request `GET /api/v1/business/beneficiaries/requirements` with the destination currency and payment method before collecting recipient details.
The API models these payment methods:
* `mobile_money`
* `bank_transfer`
* `paybill`
* `buy_goods`
* `email_transfer`
* `swift_transfer`
The capability response is provider-neutral. Availability still depends on live provider readiness and amount-specific provider limits, which are evaluated when a quote is requested.
# Quotes
Source: https://docs.northfond.xyz/quotes
Get provider-neutral rates, fees, routes, and expiry times.
Create a quote with `POST /api/v1/business/quotes`, then retrieve it with `GET /api/v1/business/quotes/:id`. A quote binds the business environment, direction, beneficiary, selected route, pricing snapshot, amounts, rate, and expiry.
Never calculate a payout from an earlier rate. Initiation rejects expired, consumed, or mismatched quotes.
Sandbox quotes are deterministic and do not call live providers. Live routing remains internal; integrations receive one normalized NorthFond response.
# Payment reviews
Source: https://docs.northfond.xyz/review-workflows
Handle payment uncertainty and policy thresholds without duplicate provider requests.
NorthFond pauses a checkout when it cannot safely determine whether another provider request should be sent or when the payment crosses a configured manual-review threshold. The payment enters `review_required` and no automatic retry is performed.
## Safe decision flow
The business receives an in-dashboard notification and, when subscribed, a `payment_intent.review_required` webhook.
An authorized NorthFond administrator inspects the provider reference, failure context, amount, customer, and audit trail.
Approval changes the checkout to `approved`. Rejection changes it to `failed`. Every decision requires a reason and is written to the audit log.
After approval, the customer returns to the original checkout and selects **Continue with M-Pesa**. Only this customer action creates a fresh quote and payment prompt.
## Guarantees
* Approval itself never sends an STK prompt.
* Review decisions are atomic and cannot be applied twice.
* Resume attempts are rate limited.
* A quote is consumed once.
* Treasury settlement is idempotent.
* Reviews have an expiry time and fail closed after expiry.
## Review events
| Event | Meaning |
| -------------------------------- | -------------------------------------------------------------------------- |
| `payment_intent.review_required` | The checkout is paused for an operator decision. |
| `payment_intent.approved` | The customer may return and continue. No payment prompt has been sent yet. |
| `payment_intent.resumed` | The customer continued and a fresh provider request began. |
| `payment_intent.rejected` | The review was rejected and the checkout cannot continue. |
| `payment_intent.completed` | Payment and treasury credit completed. |
Reviews approaching expiry appear in operator health metrics and produce a single merchant reminder. Never build an automated provider retry around `review_required`.
# Transactions
Source: https://docs.northfond.xyz/transactions
Track normalized payment state, events, settlement, and retries.
Use `GET /api/v1/business/transactions` to list transactions and `GET /api/v1/business/transactions/:id` for immutable status events and failure details.
Common states include `pending`, `awaiting_funds`, `funded`, `processing`, `action_required`, `completed`, and `failed`. Terminal transactions never regress.
Settlement details are available at `GET /api/v1/business/transactions/:id/settlement`. Confirm an external-wallet settlement with `POST /api/v1/business/transactions/:id/settlement/confirm`.
# Wallets
Source: https://docs.northfond.xyz/wallets
Use managed wallets or register verified external EVM wallets.
NorthFond supports managed and external EVM wallets. Managed wallet addresses are derived internally and cannot be supplied by callers. External wallets require a short-lived EIP-191 ownership challenge before live use.
| Endpoint | Purpose |
| ----------------------------------------------------------- | -------------------------------- |
| `POST /api/v1/business/wallets` | Register an external wallet |
| `GET /api/v1/business/wallets` | List wallets |
| `GET /api/v1/business/wallets/:id/balance` | Read chain-specific USDC balance |
| `POST /api/v1/business/wallets/:id/verification-challenges` | Create ownership challenge |
| `POST /api/v1/business/wallets/:id/verify` | Submit the signed challenge |
# Webhooks
Source: https://docs.northfond.xyz/webhooks
Verify signed events and handle retries safely.
NorthFond signs `.` with HMAC-SHA256 and sends `NorthFond-Signature: t=,v1=`.
## Verify a signature
```javascript theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyNorthFondWebhook(rawBody, signatureHeader, secret) {
const fields = Object.fromEntries(
signatureHeader.split(",").map((field) => field.split("=")),
);
const timestamp = fields.t;
const received = Buffer.from(fields.v1, "hex");
const expected = Buffer.from(
createHmac("sha256", secret)
.update(`${timestamp}.${rawBody}`)
.digest("hex"),
"hex",
);
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
return fresh && received.length === expected.length && timingSafeEqual(received, expected);
}
```
Do not parse and reserialize JSON before verification.
Reject events outside your replay window.
Calculate HMAC-SHA256 with the endpoint secret and use a constant-time comparison.
Persist processed event IDs before applying business side effects.
Acknowledge promptly and process expensive work asynchronously.
NorthFond retries failed deliveries. Dashboard users can inspect attempts, rotate endpoint secrets, send tests, and replay deliveries.
## Payment-link events
Subscribe only to the events your integration handles:
| Event | Use it for |
| -------------------------------- | --------------------------------------------------------------- |
| `payment_intent.created` | Record a newly created checkout. |
| `payment_intent.review_required` | Pause fulfillment and wait for an operator decision. |
| `payment_intent.approved` | Tell the customer they may return and continue; do not fulfill. |
| `payment_intent.resumed` | Record that customer-authorized processing restarted. |
| `payment_intent.processing` | Display an in-progress state. |
| `payment_intent.completed` | Fulfill the order after durable deduplication. |
| `payment_intent.rejected` | Close a rejected checkout. |
| `payment_intent.failed` | Display a terminal failure. |
| `payment_intent.cancelled` | Close a cancelled checkout. |
| `payment_intent.expired` | Ask the customer to create a new checkout. |
`approved` is not a successful payment. Only `payment_intent.completed` authorizes fulfillment.
## Delivery contract
* Event IDs remain stable across retries and manual replays.
* Delivery order is not guaranteed. Use the transaction's current state as the source of truth.
* Return a `2xx` response after durable receipt, then process the event asynchronously.
* Persist the event ID before applying side effects so a retry cannot duplicate work.
* Rotating an endpoint secret changes the credential used for subsequent deliveries.
The signature must be calculated from the exact raw bytes received. Parsing and serializing the JSON first can change whitespace or field order and invalidate verification.