Build crypto payments in an afternoon.

Xynex is a REST API for accepting cryptocurrency payments, sending payouts, managing subscriptions, and reconciling balances. All endpoints are versioned under /v1.

Responses are JSON envelopes — { "data": ... } on success, { "error": "..." } on failure. Times are ISO-8601 UTC. Money is returned in both decimal units and integer cents (no float surprises). Test keys (cp_test_…) hit the sandbox; live keys (cp_live_…) hit production.

Every request needs a Bearer API key in the Authorization header. Create keys in Developers → API Keys.

Authorization: Bearer cp_live_xxxxxxxxxxxxxxxx
Content-Type: application/json
Idempotency-Key: <uuid>      # POST only — recommended

Use a fresh Idempotency-Key per logical action; retries with the same key return the same result without double-charging or double-paying out.

The coin field must be the exact lowercase ticker. The ticker encodes the network — e.g. usdttrc20 is USDT on TRC-20, usdterc20 is USDT on ERC-20.

Fetch the live list:

curl -X POST https://api.xynex.app/v1/invoices \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": 49.90,
    "currency": "USD",
    "reference": "ORDER-1042",
    "description": "Pro plan — monthly",
    "customer_email": "buyer@example.com",
    "success_url": "https://yoursite.com/success",
    "cancel_url":  "https://yoursite.com/cancel",
    "expires_in_minutes": 60,
    "metadata": { "plan": "pro" }
  }'

Response includes a checkout_url — redirect or share it with your customer. Polling is also available: GEThttps://api.xynex.app/v1/invoices/{id}

Each payment represents the on-chain attempt that fulfils an invoice. Status flow: waiting → confirming → confirmed → finished (or expired / failed / partially_paid). This resource is read-only — payments are created from the hosted checkout.

Reusable URLs you can share via email or social. Each visitor checkout creates its own invoice + payment automatically.

curl -X POST https://api.xynex.app/v1/payment-links \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Pro Plan",
    "coin": "usdttrc20",
    "amount": 29.00,
    "amount_type": "fixed"
  }'

Register payout destinations before sending a payout. New beneficiaries enter pending_review and move to approved after admin verification.

curl -X POST https://api.xynex.app/v1/beneficiaries \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Vendor",
    "coin": "usdttrc20",
    "network": "trc20",
    "wallet_address": "TXYZ..."
  }'

curl -X POST https://api.xynex.app/v1/payouts \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "beneficiary_id": "<uuid>",
    "amount": 25.00,
    "coin": "usdttrc20",
    "network": "trc20",
    "notes": "weekly settlement"
  }'

Status flow: pending_admin_approval → approved → queued → processing → sent → completed (or terminal rejected / failed / cancelled). Reserved funds are auto-released on any failure.

Send up to 250 payouts in one call. The batch is created in pending_admin_approval; once approved each item becomes its own payout request.

curl -X POST https://api.xynex.app/v1/payouts/batch \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Payroll 2026-05",
    "items": [
      { "beneficiary_id": "<uuid>", "amount": 100, "coin": "usdttrc20" },
      { "wallet_address": "TXYZ...", "amount": 50,  "coin": "usdttrc20" }
    ]
  }'

Returns a single object with your available, pending, hold, and reserve balances in cents and units. Use it to gate payout UIs.

Refund a settled payment in full or partially. The refund is queued in requested until admin approval.

curl -X POST https://api.xynex.app/v1/refunds \
  -H "Authorization: Bearer $API_KEY" \
  -d '{ "payment_id": "<uuid>", "amount": 12.50, "reason": "duplicate_charge" }'

First create a plan, then subscribe customers. DELETE cancels at the end of the current period. Xynex handles renewal reminders, dunning, retries, and cancellation, and fires a webhook on every state change.

Run any amount through the live fee engine before creating an invoice or payout — useful for showing the exact net to buyers or vendors.

curl -X POST https://api.xynex.app/v1/fees/preview \
  -H "Authorization: Bearer $API_KEY" \
  -d '{ "transaction_type": "payout", "amount": 100 }'

Configure callback URLs per merchant or per payment. We send POST requests with a JSON body and an HMAC-SHA512 signature header.

X-Xynex-Signature: <hmac-sha512-of-raw-body>
X-Xynex-Event: payment.confirmed
X-Xynex-Delivery: 4f9b...
Content-Type: application/json

Verify the signature with your IPN secret (Developers → Webhooks). Respond with 2xx within 10 seconds; non-2xx responses are retried with exponential backoff for up to 24 hours.

Event types include: payment.confirmed, payment.failed, payout.queued · payout.processing · payout.sent · payout.completed · payout.failed · payout.rejected, refund.approved · refund.completed · refund.rejected, subscription.charged · subscription.failed · subscription.cancelled, dispute.opened.

Errors return a JSON envelope with an HTTP status:

{ "error": "Validation failed", "issues": [ { "path": "amount", "message": "Required" } ] }

• 400 — validation
• 401 — missing or invalid API key
• 403 — insufficient scope / plan feature disabled / capability disabled
• 404 — resource not found
• 422 — business rule violation (e.g. refund on unsettled payment)
• 429 — rate limited (default 60 req/min)
• 5xx — { "error": "...", "request_id": "<uuid>" } — retry with the same idempotency key