Online Card Payments

card_online is a payment instrument type that lets you accept credit and debit card payments directly through the NextAPI. The first supported provider is AUB (Asia United Bank), identified as ph_aub. Like QRPH, card payments slot into the existing Payment Intent model — but the flow, data requirements, and compliance obligations are meaningfully different.

How it differs from QRPH

	QRPH	AUB Direct Card
What the caller sends	Amount and account ID	PAN, CVV, expiry, billing address, browser info
Response	QR code URL	card.challenge action with requires_action status
Customer action	Scans QR in their bank app	Browser redirected to AUB 3DS authentication page
Settlement event	v2.payment_intent.succeeded	v2.payment_intent.succeeded
PCI scope on caller	None	Yes — raw card data passes through your server
Feature flag required	No	Yes — X-Feature-Flag: aub-direct-card-v1

The 3DS flow

Card payments involve two browser navigations and an async settlement step:

POST /v2/payment-intents  (card fields + redirect_url)
       ↓
Response: payment_instrument with card.challenge action
  → action.status: "requires_action"
  → action.redirect_url: AUB 3DS page
       ↓
Merchant redirects customer's browser → AUB 3DS page
       ↓
Customer authenticates with their bank
       ↓
AUB notifies NextAPI (internal callback)
NextAPI inquires AUB → settles → fires payment_intent.succeeded to your webhook
       ↓
Browser redirected → your redirect_url
       ↓
Your return handler polls GET /v2/payment-intents/{id}
  → status: "succeeded"

Two paths confirm the same outcome: the browser returns to your redirect_url, and your webhook endpoint receives payment_intent.succeeded. Both can fire — handle both idempotently.

Status machine

requires_action → succeeded
               ↘ failed
               ↘ expired

Status	Meaning
requires_action	Challenge created — customer has not yet completed 3DS
succeeded	Authenticated and settled — funds credited to the account
failed	Authorization declined or 3DS authentication failed
expired	Challenge not completed within the expiry window

The terminal statuses for card payments are succeeded and failed. This differs from QRPH, where the settled status is paid.

PCI scope

Because your server receives the raw PAN and CVV before NextAPI encrypts them for AUB, your backend is within PCI scope for card data in transit. NextAPI handles JWE encryption to AUB's requirements and never returns card fields in any response.

What you are allowed to log and retain:

• Card brand (Visa, Mastercard)
• BIN (first six digits)
• Last four digits
• Transaction status and timestamps

What must never appear in logs, databases, error contexts, or responses:

• PAN (full or partial beyond last4)
• CVV / security code
• Encrypted PAN or CVV
• 3DS cryptograms or authentication payloads
• The raw request body of the payment intent creation call

In practice: disable request body logging on the route that creates card payment intents. Validation errors for card fields should report field paths and generic messages only — never echo rejected values.

Feature flag requirement

Card online payments are in gated rollout. Two feature flags control access:

Flag	Covers
aub-direct-card-v1	3DS-authenticated card payments (standard path)
aub-direct-card-non-3ds-v1	Non-3DS direct sale (not generally available)

Pass the flag as a request header:

curl -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -X POST "https://api.partners.nextpay.world/v2/payment-intents" \
  -H "X-Feature-Flag: aub-direct-card-v1" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Requests without the flag return a 422. Contact NextPay to enable card_online for your workspace. Non-3DS access requires a separate compliance and commercial approval.

Related

• Accept an AUB Direct Card Payment — step-by-step guide
• Build a Card Checkout — end-to-end tutorial
• Collections Lifecycle — how card_online fits the broader Money In model
• Multi-Provider Routing — ph_aub as a provider under the card_online type
• Security and Compliance — NextPay's PCI operating model