Skip to main content

Quick Start — Your First Payment in 15 Minutes

This guide walks you through creating a payment transaction from scratch. No prior knowledge of the platform required.

Prerequisites​

  • Your API key (find it in Partner Area → Settings → API Keys)
  • curl installed, or any HTTP client

Step 1 — Check your connection​

curl https://4pay.online/api/v1/health

Expected response:

{ "status": "ok" }

Step 2 — Create a transaction​

curl -X POST https://4pay.online/api/v1/transactions \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "params": {
      "type": "payment",
      "amount": 1000,
      "currency": "USD",
      "txid": "order-12345",
      "returnUrl": "https://yoursite.com/success",
      "failUrl": "https://yoursite.com/fail"
    }
  }'
Amount format

amount is in the smallest currency unit (cents, pence, kopecks). 1000 = $10.00 USD.

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "created",
  "txid": "order-12345",
  "amount": 1000,
  "currency": "USD",
  "payment_url": "https://4pay.online/pay/550e8400-...",
  "created_at": "2026-03-01T10:00:00Z"
}

Redirect your user to payment_url. They will see the hosted payment page where they can complete the payment.

Step 3 — Check the transaction status​

curl https://4pay.online/api/v1/transactions/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: YOUR_API_KEY"

Transaction statuses:

StatusMeaning
createdTransaction created, awaiting payment
pendingSubmitted to the payment provider
processingBeing processed by the provider
chargedPayment successful ✅
failedPayment failed — provider declined
rejectedRejected before reaching the provider (no routing, limits)
cancelledCancelled by partner or user
refundedRefund completed

Step 4 — Receive webhook notifications​

Instead of polling, set up a notify_url to receive real-time status updates:

curl -X POST https://4pay.online/api/v1/transactions \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "params": {
      "type": "payment",
      "amount": 1000,
      "currency": "USD",
      "txid": "order-12346",
      "returnUrl": "https://yoursite.com/success",
      "failUrl": "https://yoursite.com/fail",
      "notifyUrl": "https://yoursite.com/webhooks/payment"
    }
  }'

When the transaction status changes, a POST request will be sent to your notifyUrl. See Webhooks for the full event format and signature verification.

Step 5 — Issue a refund​

curl -X PUT https://4pay.online/api/v1/transactions/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "params": {
      "type": "refund",
      "amount": 500
    }
  }'

For a full refund, omit amount or set it equal to the original transaction amount.

Next steps​