Payment Flows

This guide covers all payment flows supported by 4pay.online: direct card payments, hosted payments, payouts, refunds, and cascade routing.

Transaction Lifecycle

Every transaction follows this state machine:

created → pending → processing → charged ✅
                               → failed ❌
                               → rejected ❌

charged → refunded (partial or full)
created/pending → cancelled

Status	Description
`created`	Transaction initialized
`pending`	Routing and validation in progress
`processing`	Sent to payment provider
`charged`	Payment confirmed, funds received
`failed`	Provider declined the transaction
`rejected`	Validation, routing, or compliance check failed
`cancelled`	Cancelled by user or timeout
`refunded`	Partial or full refund processed

Direct Card Payment

For PCI DSS certified partners who handle card data directly.

Partner API                     4pay.online                    Provider
    │                               │                             │
    ├─── POST /transactions ───────►│                             │
    │    (card data included)       │── route + validate ────────►│
    │                               │                             │
    │                               │◄── 3DS required ───────────┤
    │◄── action_required: true ─────┤                             │
    │                               │                             │
    ├─── POST /additional_params ──►│── 3DS verification ────────►│
    │    (OTP or 3DS data)          │                             │
    │                               │◄── charged ────────────────┤
    │◄── webhook: charged ──────────┤                             │

Create Payment

curl -X POST https://4pay.online/api/v1/transactions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "txid": "order_123",
    "type": "payment",
    "amount": 10000,
    "currency": "USD",
    "card_number": "4111111111111111",
    "card_exp_month": "12",
    "card_exp_year": "2027",
    "card_cvv": "123",
    "description": "Order #123",
    "return_url": "https://your-site.com/result"
  }'

Handle 3DS Authentication

If the response includes action_required: true, redirect the customer to the auth_url. After 3DS verification, submit the authentication data:

curl -X POST https://4pay.online/api/v1/transactions/additional_params_for_auth/TX_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"otp": "123456"}'

Hosted Payment

For partners without PCI DSS certification. The customer enters card details on a 4pay.online-hosted page.

Partner API                     4pay.online                    Customer
    │                               │                             │
    ├─── POST /transactions ───────►│                             │
    │    (NO card data)             │                             │
    │◄── widget_url ────────────────┤                             │
    │                               │                             │
    │    redirect customer ─────────┼─────────────────────────────►
    │                               │◄── card data ──────────────┤
    │                               │── process payment ──►       │
    │◄── webhook: charged ──────────┤                             │

Create Hosted Payment

curl -X POST https://4pay.online/api/v1/transactions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "txid": "order_456",
    "type": "payment",
    "amount": 5000,
    "currency": "EUR",
    "description": "Order #456",
    "return_url": "https://your-site.com/result"
  }'

Response includes widget_url — redirect the customer there. After payment, the customer returns to return_url and you receive a webhook.

Payout

Send funds from your account to a recipient (card, bank account, wallet).

curl -X POST https://4pay.online/api/v1/transactions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "txid": "payout_789",
    "type": "payout",
    "amount": 25000,
    "currency": "USD",
    "card_number": "4111111111111111",
    "description": "Withdrawal request #789"
  }'

Payout follows the same lifecycle: created → pending → processing → charged/failed.

Refund

Issue a full or partial refund on a charged transaction.

Full Refund

curl -X PUT https://4pay.online/api/v1/transactions/TX_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"type": "refund"}'

Partial Refund

curl -X PUT https://4pay.online/api/v1/transactions/TX_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"type": "refund", "amount": 5000}'

Two-Phase Payment (Authorize + Capture)

Some providers support authorization (hold) followed by capture (charge). The platform holds funds first, then captures when you confirm.

authorize → charging (funds held) → commit → charged

To manually commit an authorized transaction:

curl -X POST https://4pay.online/api/v1/transactions/commit/TX_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Cascade Routing

When a provider fails, the platform automatically retries with the next available provider:

Provider A (priority 0) → failed → rollback hold
                                    ↓
Provider B (priority 1) → failed → rollback hold
                                    ↓
Provider C (priority 2) → charged ✅

Cascade is transparent to the partner. You always receive the final result via webhook. Configure routing priorities in the Admin Console under Terminals & Routing.

Amount Fields

Every transaction response includes three amount fields:

Field	Description	Example
`amount`	Original requested amount	10000
`amount_with_fee`	Amount including all fees	10500
`amount_dest`	Amount received by destination	9500

For payments: customer pays amount, merchant receives amount_dest. For payouts: merchant sends amount, recipient receives amount_dest.

All amounts are in minor units (cents, kopecks). For example, 10000 = 100.00 USD.

Webhook Notifications

You receive webhooks at each status change. See Webhooks for setup details.

Example webhook payload:

{
  "type": "payment",
  "txid": "order_123",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "charged",
  "amount": 10000,
  "amount_dest": 9500,
  "amount_with_fee": 10500,
  "currency": "USD"
}

Idempotency

Always use the transaction id (UUID) for deduplication. The platform may send the same webhook multiple times.

Recovery & Resilience

Transaction state is persisted at every processing stage
If a node crashes mid-flow, recovery automatically resumes from the last checkpoint
No manual intervention required — the platform guarantees at-least-once delivery

Next Steps

Code Examples — Python, Node.js, PHP implementations
Webhooks — Webhook setup and signature verification
Error Reference — Error codes and troubleshooting
Sandbox & Testing — Test cards and sandbox environment

Payment Flows

Transaction Lifecycle​

Direct Card Payment​

Create Payment​

Handle 3DS Authentication​

Hosted Payment​

Create Hosted Payment​

Payout​

Refund​

Full Refund​

Partial Refund​

Two-Phase Payment (Authorize + Capture)​

Cascade Routing​

Amount Fields​

Webhook Notifications​

Recovery & Resilience​

Next Steps​