Accept payments through the API

A payment intent represents one amount owed to your business. It carries your order reference, accepted payment method, settlement preference, customer context, expiry, and payment lifecycle state. Use a server-side API key with payment_intents:read, payment_intents:write, and treasury:read.

Direct stablecoin collection to a unique payment-intent address is not yet certified for live use. Deposit monitoring, confirmation, treasury crediting, and sweeping must be enabled by NorthFond before you display such an address to a real customer. Use sandbox for this flow until NorthFond confirms live readiness for your business.

Sandbox end-to-end example

Create a payment intent

Use a durable order identifier as external_reference. Send the same idempotency key when retrying this exact request.

IDEMPOTENCY_KEY="payment-order-1042"

curl --fail-with-body --silent --show-error \
  --request POST \
  --url https://payment.gideondevrel.xyz/api/v1/business/payment-intents \
  --header "Authorization: Bearer $NORTHFOND_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{
    "external_reference": "order_1042",
    "amount": { "currency": "KES", "value": "100" },
    "accepted_payment_methods": ["mobile_money"],
    "settlement": { "mode": "stablecoin", "asset": "USDC", "chain": "base" },
    "customer": {
      "reference": "student_88",
      "email": "student@example.com",
      "name": "Example Student"
    },
    "metadata": { "course_id": "course_12" },
    "expires_in_seconds": 1800
  }'

Complete the sandbox payment

Simulation is accepted only by sandbox credentials and never moves funds.

PAYMENT_INTENT_ID="replace_with_payment_intent_id"

curl --fail-with-body --silent --show-error \
  --request POST \
  --url "https://payment.gideondevrel.xyz/api/v1/business/payment-intents/$PAYMENT_INTENT_ID/simulate" \
  --header "Authorization: Bearer $NORTHFOND_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: simulate-order-1042" \
  --data '{ "payment_method": "mobile_money" }'

Verify the payment

Retrieve the intent and require status to equal completed before granting access to the purchased resource.

curl --fail-with-body --silent --show-error \
  --url "https://payment.gideondevrel.xyz/api/v1/business/payment-intents/$PAYMENT_INTENT_ID" \
  --header "Authorization: Bearer $NORTHFOND_API_KEY"

Reconcile the treasury

Confirm that the payment appears in deposits and that the treasury balance reflects the completed settlement.

curl --fail-with-body --silent --show-error \
  --url "https://payment.gideondevrel.xyz/api/v1/business/treasury/deposits?limit=25" \
  --header "Authorization: Bearer $NORTHFOND_API_KEY"

curl --fail-with-body --silent --show-error \
  --url https://payment.gideondevrel.xyz/api/v1/business/treasury/balances \
  --header "Authorization: Bearer $NORTHFOND_API_KEY"

Production collection

For the current controlled beta, use a NorthFond-hosted payment link for live mobile-money collection. The hosted checkout gathers the customer phone and network, starts the provider request, and updates the underlying payment intent. Do not fulfill from a checkout redirect, awaiting_payment, approved, or processing. Fulfill only after a signed payment_intent.completed webhook, then retrieve the payment intent and reconcile its treasury deposit using your own durable external_reference.

Status handling

Status	Integration action
`awaiting_payment`	Show payment instructions or wait for the customer
`funds_detected`	Keep the order pending while payment is confirmed
`processing`	Keep the order pending
`review_required`	Pause fulfillment and wait for an operator decision
`approved`	Ask the customer to resume; approval is not payment
`completed`	Reconcile and fulfill exactly once
`failed`, `cancelled`, `expired`	Do not fulfill

See Webhooks, Idempotency, and Operational readiness before enabling live traffic.

Get started

Model your integration

On-ramp

Off-ramp

Accept payments

Activity

Build reliably

Sandbox end-to-end example

Production collection

Status handling

​Sandbox end-to-end example

​Production collection

​Status handling

Sandbox end-to-end example

Production collection

Status handling