XPay documentation

Quickstart

XPay has no separate merchant onboarding. Any XCall account can create a payment link, and any XCall account can pay one. Three calls get you from nothing to a payment you can watch settle.

1. Get a token

   Sign in with your XCall email or username. The token goes in the Authorization header of everything after this.

   1 — sign in Copy

   curl -X POST https://api.xcall.cc/sandbox/v1/auth/login \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H 'platform: web' \
     -H 'imei: 8f14e45fceea167a5a36dedd4bea2543' \
     -d '{
       "username": "[email protected]",
       "password": "sandbox-Pa55word"
     }'

2. Create a link

   A title and a currency are the only required fields. Leave amount out for an open-amount link.

   2 — create Copy

   curl -X POST https://api.xcall.cc/sandbox/v1/xpay/create \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer YOUR_TOKEN' \
     -d '{
       "title": "Invoice #1048",
       "currency": "USDT",
       "amount": "250"
     }'

3. Send the customer to checkout

   The UUID from step 2 is the link's public id. Put it in the checkout URL, or encode that URL as a QR code.

   3 — checkout URL Copy

   https://app.xcall.cc/payment?link=<uuid>

API conventions

Four things surprise people coming from a REST gateway. Read these before the reference.

Request headers

Authentication

Every XPay endpoint except xpay/show needs a bearer token. Tokens come from POST /auth/login and are sent as Authorization: Bearer <token>.

{
  "status": true,
  "data": {
    "token": "84|kQx2Vd…",
    "api_key": "…",
    "token_type": "Bearer",
    "user": { "id": 2087, "username": "sandbox_payer", "email": "[email protected]" }
  }
}

The new-device gate

Signing in from an imei the account has not used before does not return a token. It emails a code and returns a challenge instead:

{
  "status": true,
  "data": {
    "needs_device_verification": true,
    "identifier": "[email protected]",
    "message": "A verification code has been sent to your email."
  }
}

Confirm it with POST /auth/verify-device ({ username, code }), which returns the same envelope as a successful login and trusts that device from then on. To avoid hitting this on every call, generate one random 32-character imei per installation, store it, and reuse it.

CAPTCHA

Sign-in, sign-up and xpay/pay are CAPTCHA-gated. Call POST /captcha/generate, show data.image (a data URI) to the user, and send back captcha_id plus captcha_answer. Each challenge is single-use — fetch a fresh one after any failure.

Sandbox & test account

The sandbox is exposed through the isolated /sandbox/v1 path on the main API host. A guard limits it to two published test accounts and their payment links; production account tokens are rejected. The identifiers below never change.

Ready-made payment links

Try one call right now

This needs no token and no account — it is the same call the checkout page makes:

curl -X POST https://api.xcall.cc/sandbox/v1/xpay/show \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"uuid":"5b1d4e2a-9c3f-4a17-8e60-2f7c1b9d4e35"}'

Pay a link from this page

Running the sandbox yourself

The accounts above are created by an idempotent seeder in the XCall backend. Run:

php artisan db:seed --class="Database\Seeders\XPaySandboxSeeder"

It is idempotent — re-running restores the payer's balance and leaves the link UUIDs alone. It refuses to run when APP_ENV=production unless you set XPAY_SANDBOX_SEED=true, because it creates accounts with published passwords.

Endpoint reference

Eight endpoints, all POST, all under https://api.xcall.cc/v1 in production. Paths below are shown against the sandbox.

{
  "uuid": "5b1d4e2a-9c3f-4a17-8e60-2f7c1b9d4e35"
}

{
  "status": true,
  "data": {
    "uuid": "5b1d4e2a-9c3f-4a17-8e60-2f7c1b9d4e35",
    "title": "Sandbox — fixed amount",
    "description": "A 25 USDT invoice. The payer cannot change the amount.",
    "amount": "25.000000",
    "amount_editable": false,
    "currency": "USDT",
    "payee": "sandbox_merchant",
    "status": "active"
  }
}

{
  "title": "Design retainer — October",
  "description": "Invoice #1048",
  "amount": "250",
  "currency": "USDT"
}

{
  "status": true,
  "data": {
    "id": 31,
    "uuid": "b7f2c1a9-4d3e-4f10-9a22-7c5e8d1b0f44",
    "user_id": 1042,
    "title": "Design retainer — October",
    "description": "Invoice #1048",
    "amount": "250.000000000000000000",
    "currency_code": "USDT",
    "status": "active",
    "expires_at": null,
    "redirect_url": null,
    "callback_url": null,
    "created_at": "2026-09-26T14:02:11.000000Z",
    "updated_at": "2026-09-26T14:02:11.000000Z"
  }
}

{
  "page": 1,
  "per_page": 20
}

{
  "status": true,
  "data": [
    {
      "id": 31,
      "uuid": "b7f2c1a9-4d3e-4f10-9a22-7c5e8d1b0f44",
      "title": "Design retainer — October",
      "amount": "250.000000000000000000",
      "currency_code": "USDT",
      "status": "active",
      "paid_count": 2
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1,
    "last_page": 1
  }
}

{
  "uuid": "b7f2c1a9-4d3e-4f10-9a22-7c5e8d1b0f44",
  "amount": "275",
  "status": "active"
}

{
  "status": true,
  "data": {
    "uuid": "b7f2c1a9-4d3e-4f10-9a22-7c5e8d1b0f44",
    "amount": "275.000000000000000000",
    "status": "active"
  }
}

{
  "uuid": "b7f2c1a9-4d3e-4f10-9a22-7c5e8d1b0f44"
}

{
  "status": true,
  "data": {
    "uuid": "b7f2c1a9-4d3e-4f10-9a22-7c5e8d1b0f44",
    "status": "disabled"
  }
}

{
  "uuid": "b7f2c1a9-4d3e-4f10-9a22-7c5e8d1b0f44"
}

{
  "status": true,
  "data": {
    "link": { "uuid": "b7f2c1a9-…", "title": "Design retainer — October" },
    "count": 2,
    "total_received": "499.900000",
    "total_fees": "0.100000",
    "payments": [
      {
        "id": 88,
        "payer_user_id": 2087,
        "payer_email": "[email protected]",
        "amount": "250.000000000000000000",
        "fee": "0.050000000000000000",
        "net_amount": "249.950000000000000000",
        "currency_code": "USDT",
        "status": "paid",
        "paid_at": "2026-09-26T14:20:02.000000Z"
      }
    ]
  }
}

{
  "uuid": "5b1d4e2a-9c3f-4a17-8e60-2f7c1b9d4e35",
  "captcha_id": "8f14e45f-ea9c-4d1b-9b8a-3c2d1e0f7a6b",
  "captcha_answer": "7K2M9"
}

{
  "status": true,
  "data": {
    "id": 88,
    "link_id": 31,
    "payer_user_id": 2087,
    "amount": "25.000000000000000000",
    "fee": "0.005000000000000000",
    "net_amount": "24.995000000000000000",
    "currency_code": "USDT",
    "status": "paid",
    "paid_at": "2026-09-26T14:20:02.000000Z"
  }
}

{
  "status": "paid",
  "page": 1
}

{
  "status": true,
  "data": [
    {
      "id": 88,
      "amount": "25.000000000000000000",
      "status": "paid",
      "link": { "uuid": "5b1d4e2a-…", "title": "Sandbox — fixed amount" },
      "payer": { "id": 2087, "username": "sandbox_payer" }
    }
  ],
  "meta": { "current_page": 1, "per_page": 20, "total": 1, "last_page": 1 }
}

Payment lifecycle

What actually happens between a customer tapping Pay and the money being in your wallet.

1. 1

   Link created active

   The merchant calls `xpay/create`. Nothing is reserved and nothing is charged.

2. 2

   Payer opens the checkout active

   The page calls the public `xpay/show` to render the title, amount and merchant. No authentication yet.

3. 3

   Payer confirms pending → paid

   A payment row is written as `pending`, then the ledger moves inside one transaction and the row flips to `paid` with `paid_at` set. A failure anywhere rolls the whole thing back.

4. 4

   Balances move paid

   The payer is debited the gross. The merchant is credited gross minus fee. The platform wallet is credited the fee. Two transactions are recorded — `xpay_out` for the payer, `xpay_in` for the merchant.

5. 5

   Both sides notified paid

   The merchant gets an in-app notification and an email; the payer gets an in-app notification. The link stays active for the next customer.

Fees & amounts

XPay charges 0.02% of each payment, taken from the merchant's side. The payer is debited the gross; the merchant is credited gross minus fee; the platform wallet receives the fee. Nothing is added on top of what the customer sees.

The rate is configurable server-side, so read it rather than hardcoding it. POST /fee is public and returns the whole schedule:

{
  "status": true,
  "data": {
    "transfer_rate": "0.0001",
    "xpay_rate": "0.0002",
    "withdraw_network_multiplier": "3",
    "withdraw_fee": { "USDT": "5", "TRX": "5" }
  }
}

Precision

Amounts are DECIMAL(36,18) in the database and always serialised as strings. A JSON number cannot hold them without loss — parse with a decimal library, compare as decimals, and never round before sending.

Errors

Failures come back with status: false and a human-readable message. Validation failures add an errors map keyed by field name.

{
  "status": false,
  "message": "This payment link is no longer active."
}

// Validation failures add a field map:
{
  "status": false,
  "message": "The title field is required.",
  "errors": { "title": ["The title field is required."] }
}

Note that most business-rule failures are 422, not 404 or 409 — including an unknown link UUID. Branch on message, or on your own pre-checks, rather than on the status code alone.

Go-live checklist

• Swap the base URL from the sandbox to https://api.xcall.cc/v1.
• Sign in as your real XCall account and store that token — sandbox tokens are not valid in production.
• Generate and persist one imei per installation so you are not re-verifying the device on every login.
• Read the fee rate from POST /fee instead of hardcoding 0.02%.
• Parse every amount as a decimal string.
• Handle the needs_device_verification branch of the login response.
• Fetch a fresh CAPTCHA after every failed xpay/pay.
• Poll xpay/report to reconcile, since callbacks are not dispatched yet.
• Disable a link after payment if it represents a single invoice — links are reusable by default.