Collections Lifecycle

Collections are how you receive money through NextAPI. There are two mechanisms: Funding Methods (persistent, static) and Payment Intents (dynamic, one-time). This page explains the lifecycle of each and how funds flow from payor to your account.

Two collection mechanisms

	Funding Method	Payment Intent
Type	Static, persistent	Dynamic, one-time
QRPH code	Same code reused for multiple payments	Unique code per payment
Use case	Virtual bank account, recurring deposits	Invoice payment, checkout
Expires	Never (until archived)	Configurable expiry
Amount	Any amount (payor-defined)	Specific amount (you define)

Funding Methods

A Funding Method is a persistent payment endpoint — a virtual bank account or static QRPH code linked to a NextAPI account. Payors can use it repeatedly.

Lifecycle

CREATED → ACTIVE → ARCHIVED

State	Description
CREATED	Funding method provisioned with provider; not yet active
ACTIVE	Accepting payments; QRPH code or account number is live
ARCHIVED	Deactivated; no longer accepts new payments

Payment receipt flow

Payor scans QRPH / sends bank transfer
        │
        ▼
Provider receives funds
        │
        ▼
NextAPI receives provider webhook
        │
        ▼
Account balance updated (pending → available)
        │
        ▼
NextAPI fires webhook to your endpoint
  event: funding_method.payment_received

Creating a Funding Method

curl -X POST https://api.partners.nextpay.world/v2/funding-methods \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "acc_abc123",
    "type": "qrph",
    "external_id": "fm-merchant-001"
  }'

The response includes the QRPH payload or virtual account details your payor uses to send funds.

Payment Intents

A Payment Intent is a single-use collection request for a specific amount. It generates a unique QRPH code that expires after a configurable window.

Lifecycle

CREATED → PENDING → COMPLETED
    │          │
    └──────────┴──→ EXPIRED / CANCELLED

State	Description
CREATED	Intent created; QRPH code generated but payor hasn't scanned
PENDING	Payor has scanned; payment in processing
COMPLETED	Payment received and settled to account
EXPIRED	Expiry time reached before payment
CANCELLED	Cancelled via API

Payment receipt flow

POST /v2/payment-intents
        │
        ▼
  QRPH code generated
        │
        ▼ (share QR with payor)
Payor scans and pays
        │
        ▼
NextAPI receives provider confirmation
        │
        ▼
Intent → COMPLETED
Account balance credited
        │
        ▼
NextAPI fires webhook to your endpoint
  event: payment_intent.completed

Creating a Payment Intent

curl -X POST https://api.partners.nextpay.world/v2/payment-intents \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: pi-order-checkout-789" \
  -d '{
    "account_id": "acc_abc123",
    "amount": 50000,
    "currency": "PHP",
    "description": "Order #789",
    "external_id": "order-789",
    "expires_at": "2024-01-16T10:00:00Z"
  }'

Amount is in centavos: 50000 = PHP 500.00.

Balance update timing

Phase	Available balance	Pending balance
Before payment	Unchanged	Unchanged
Payment scanned / in-flight	Unchanged	Increases
Payment confirmed	Increases	Returns to 0

The pending → available transition triggers the webhook event. The available balance is what you can use for payouts.

Webhook events

Event	Trigger
funding_method.payment_received	Funds received into a Funding Method
payment_intent.completed	Payment Intent payment confirmed
payment_intent.expired	Payment Intent expired without payment

Configure webhooks via POST /v2/webhooks. See Understanding Webhooks for payload structure.

Related

• Understanding Your Wallet Structure — how accounts hold and track balances
• Understanding Webhooks — real-time event notifications
• API Reference: Funding Methods — funding method endpoints
• API Reference: Payment Intents — payment intent endpoints