Transactions

The transaction is the core object of the 4pay.online API. Every payment, payout, and refund is a transaction.

Base URL: https://4pay.online/api/v1/transactions

---

Create a transaction

POST /api/v1/transactions

Request body

{
  "params": {
    "type": "payment",
    "amount": 1000,
    "currency": "USD",
    "txid": "order-12345",
    "returnUrl": "https://yoursite.com/success",
    "failUrl": "https://yoursite.com/fail",
    "notifyUrl": "https://yoursite.com/webhooks/payment"
  }
}

Parameters

Field	Type	Required	Description
type	string	✅	Transaction type: payment, payout
amount	integer	✅	Amount in smallest currency unit (cents)
currency	string	✅	ISO 4217 currency code (USD, EUR, USDT, …)
txid	string	✅	Your unique order ID. Must be unique per terminal
returnUrl	string	✅	Redirect URL on successful payment
failUrl	string	✅	Redirect URL on failed/cancelled payment
notifyUrl	string	—	Webhook URL for status notifications
hosted	boolean	—	true (default): redirect to hosted page. false: server-to-server
description	string	—	Payment description shown to the payer
customer	object	—	Payer info: { email, phone, name }
lang	string	—	UI language: en, ru, ar, es, …
metadata	object	—	Your custom key-value data, returned in webhooks

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 to complete the payment.

---

Get a transaction

GET /api/v1/transactions/:id

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

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "charged",
  "txid": "order-12345",
  "amount": 1000,
  "amount_with_fee": 1050,
  "amount_dest": 950,
  "currency": "USD",
  "currency_dest": "USD",
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:05:00Z"
}

Amount fields

Field	Description
amount	Original transaction amount (what the payer pays)
amount_with_fee	Amount including platform fee
amount_dest	Amount credited to you (after fee deduction)

---

List transactions

GET /api/v1/transactions

curl "https://4pay.online/api/v1/transactions?status=charged&limit=50" \
  -H "x-api-key: YOUR_API_KEY"

Query parameters

Parameter	Type	Description
status	string	Filter by status
currency	string	Filter by currency
type	string	Filter by type: payment, payout
from	ISO 8601	Created after this datetime
to	ISO 8601	Created before this datetime
limit	integer	Results per page (default: 20, max: 100)
offset	integer	Pagination offset

---

Aggregate transactions

Get summarized stats across multiple transactions:

GET /api/v1/transactions/aggregate

curl "https://4pay.online/api/v1/transactions/aggregate?currency=USD&status=charged" \
  -H "x-api-key: YOUR_API_KEY"

---

Update a transaction

Use PUT /api/v1/transactions/:id to issue a refund or cancel a transaction.

Refund

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

Omit amount for a full refund.

Cancel

curl -X PUT https://4pay.online/api/v1/transactions/550e8400-... \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "params": {
      "type": "cancel"
    }
  }'

---

Two-phase payments (Authorize + Capture)

For providers that support two-phase, first create with type: "payment" — the funds are held but not captured. Then commit:

POST /api/v1/transactions/commit/:id

curl -X POST https://4pay.online/api/v1/transactions/commit/550e8400-... \
  -H "x-api-key: YOUR_API_KEY"

---

3DS / Additional authentication

If a transaction enters a state requiring additional authentication (3DS OTP, etc.), the webhook payload will contain action_required: true and a redirect URL. After the user completes authentication:

POST /api/v1/transactions/additional_params_for_auth/:id

{
  "params": {
    "otp": "123456"
  }
}

---

Transaction lifecycle

created
  └─► pending
        └─► processing
              ├─► charged     ✅ Success
              ├─► failed      ❌ Provider declined
              └─► rejected    ❌ No routing / limits exceeded
  └─► cancelled               Cancelled before processing
charged
  └─► refunded                Refund completed