Payments API

Endpoints

The Payment Object

{
  "id": "tx_b84050910b493a1e",
  "status": "pending",
  "amount": "20",
  "currency": "USD",
  "checkout_url": "https://checkout.vexutopia.com/pay?session=tx_b84050910b493a1e",
  "return_url": "https://yoursite.com/order/success",
  "provider": "card",
  "customer_email": "[email protected]",
  "customer_name": "Jane Smith",
  "failure_reason": null,
  "metadata": {
    "order_id": "1234"
  },
  "created_at": "2026-04-06T19:47:36.807Z",
  "updated_at": "2026-04-06T19:47:39.020Z",
  "expires_at": "2026-04-07T19:47:38.000Z",
  "completed_at": null
}

Create a Payment

curl -X POST https://vexutopia.com/api/v1/payments \
  -H "X-API-Key: vex_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "20",
    "currency": "USD",
    "locale": "fr",
    "return_url": "https://yoursite.com/order/success",
    "customer_email": "[email protected]",
    "metadata": {
      "order_id": "1234"
    }
  }'

const response = await fetch('https://vexutopia.com/api/v1/payments', {
  method: 'POST',
  headers: {
    'X-API-Key': 'vex_test_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: '20',
    currency: 'USD',
    return_url: 'https://yoursite.com/order/success',
    customer_email: '[email protected]',
    metadata: { order_id: '1234' }
  })
});

const payment = await response.json();

// Redirect the customer to complete payment
window.location.href = payment.checkout_url;

{
  "id": "tx_b84050910b493a1e",
  "status": "pending",
  "checkout_url": "https://checkout.vexutopia.com/pay?session=tx_b84050910b493a1e",
  "expires_at": "2026-04-07T20:16:49.470Z",
  "amount": "20",
  "currency": "USD",
  "created_at": "2026-04-06T20:16:47.932Z"
}

Crypto (direct)

Pass crypto: true on POST /v1/payments to start a cryptocurrency checkout. The response checkout_url is on vexutopia.com/pay/crypto/<id> (embedded hosted flow; your customer completes payment there). This rail is not available as a choice on the standard multi-method /pay page — your backend must opt in per payment.

• Fees — one all-in percentage, shown as a single rate on the invoice (see Payment Providers)
• Minimum — USD 3 equivalent in your requested currency
• Underpayment tolerance — sends within 1% of the quoted amount still settle as completed, for the full amount. A larger shortfall leaves the payment partially paid (see below)
• return_url — may include {payment_id}, {order_id}, {transaction_id}, and {status}; these are replaced when the customer is sent back to your site
• Webhooks — same events as other rails; payment_method is crypto

Example request

curl -X POST https://vexutopia.com/api/v1/payments \
  -H "X-API-Key: vex_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10.00",
    "currency": "USD",
    "crypto": true,
    "return_url": "https://yoursite.com/pay/return?id={payment_id}&status={status}",
    "webhook_url": "https://yoursite.com/api/webhooks/vexutopia"
  }'

Store the returned id in your own database before redirecting — your return page should look up that id server-side (do not rely on the URL alone for fulfillment).

Partial payments

Two rails can leave a payment part-paid. Crypto: customers sometimes send less than the invoice, most often because their exchange deducts a withdrawal fee from the amount sent. When the shortfall is more than 1%, the payment is not completed and nothing is credited yet. Gift cards: a customer enters a code worth less than the order. The code is used up, so its value counts toward the order. The customer has 24 hours to add another code. You can click Accept before then. When the window ends, an order with at least $2 received completes at that amount on its own. Under $2 it expires. Deliver for amount on payment.completed only. A worked example, including how to turn a short payment into credits, is under Gift Card → What to deliver. Crypto underpayments follow the rest of this section:

• We send payment.partial with status partially_paid, the invoice amount and amount_received in your currency. Crypto sends it once and adds asset and network for what arrived on-chain; gift cards send it each time a code is credited while the order is still short.
• The checkout asks the customer for the rest. If they pay it in time (48 hours for crypto, 24 hours after the last gift card code), the payment completes for the full amount as usual. A gift card order that still has at least $2 received when that window ends completes at the received amount. Under $2 it expires with amount_received on payment.expired.
• The payment shows as Partially paid on your Payments page, and the crypto_deposit object on GET /api/v1/payments/{id} has status underpaid with received_amount and remaining_amount.

Fulfil only on payment.completed, for amount. payment.partial and payment.expired are information only: nothing has been credited to you yet, and the customer may still pay the rest, in which case the payment completes for the full amount. Granting on the first notice would give the customer the product twice.

Accepting a partial payment

If you are happy to take the shortfall, click Accept on the payment in your dashboard (Payments → the banner, or any payment marked Partially paid). Account owners and admins can do this. The payment then completes at the amount the customer actually sent:

• Your balance is credited for the received amount minus fees (the fee applies to the settled amount). The shortfall is never credited.
• payment.completed fires with amount set to the received amount and amount_requested set to the original invoice amount. If your handler checks that amount matches the order total, allow for this case.
• GET /api/v1/payments/{id} returns the same amount and amount_requested.
• Accepting can't be undone. Anything the customer sends to the payment after you accept is not credited, so tell them it's settled. If they had already paid the rest when you click Accept, the payment completes for the full amount instead.

If you don't accept a crypto underpayment, it stays partially paid and nothing is credited. Contact support if you want those funds returned to the customer. A gift card code cannot be un-redeemed, so a part-paid gift card order completes at the received amount when its 24-hour window ends (under $2 it expires instead). Deliver for amount. See Gift Card → Part-paid orders.

Mastercard

Pass mastercard: true on POST /v1/payments to send the customer straight to the Mastercard checkout. The response checkout_url is on vexutopia.com/pay/mastercard/<id>. Use it for a dedicated “Pay with Mastercard” button next to your other payment options — the same way crypto: true gives crypto its own button.

Getting access

Mastercard is the one rail that needs approval, and it is granted per site. Ask for it under Settings → Payment Methods — we review the site and enable it. Until then this call returns 403 MASTERCARD_NOT_ENABLED. Nothing else about your account changes while a request is open.

Where it appears, and your two switches

Both live under Settings → Payment Methods once the site is approved.

• Mastercard — the method itself. Off means off everywhere, including this call, which then returns 403 MASTERCARD_DISABLED. It is on by default once approved.
• Show Mastercard on your main checkout — where it is offered, not whether. On (the default), customers see a Mastercard option on your multi-method /pay checkout alongside your other methods. Off, they do not, and Mastercard is reached only through mastercard: true — which opens a checkout carrying Mastercard alone. Use that if you would rather have a separate “Pay with Mastercard” button on your site than a card option among many.

The second switch never affects this endpoint: a dedicated Mastercard checkout keeps working whether or not the rail is shown on your main checkout.

• Currencies — price in USD or EUR. The card is always charged in EUR; USD amounts are converted at our rate when the checkout opens.
• Fees — 19% per transaction, deducted from the order amount when you settle. No payout fee and no refund fee; a chargeback costs EUR 100. See the fee summary on the Payment Providers page.
• Card fee — the card network adds a EUR 0.62 fixed fee to every order, charged to your customer on top of the order total and shown on the checkout before they enter their card. It is not part of your fee: your customer pays it and it never passes through your balance, so it neither adds to nor reduces your payout — your fee is the 19% above. Worth knowing on small orders: EUR 0.62 on a EUR 3 order is about a fifth again on top.
• Per-order range — EUR 2 minimum, with a ceiling of about EUR 500 that can shift slightly over time. Outside it you get 422 with AMOUNT_BELOW_MINIMUM or AMOUNT_ABOVE_MAXIMUM.
• Countries — Mastercard is not available for customers in: Afghanistan, Albania, Barbados, Burkina Faso, Cambodia, Cayman Islands, Cuba, Haiti, Jamaica, Jordan, Mali, Malta, Morocco, Myanmar, Nicaragua, North Korea, Pakistan, Panama, Philippines, Senegal, Somalia, South Sudan, Syria, Uganda, Venezuela, Yemen. Pass the customer's country and a payment for one of these returns 422 COUNTRY_NOT_SUPPORTED straight away, and the Mastercard option is not shown on your main checkout. Without country we cannot check up front, and the card is declined at payment instead — offer these customers another method.
• return_url — supports {payment_id}, {order_id}, {transaction_id} and {status}, like the other hosted checkouts.
• Webhooks — same events as other rails, carrying the id this call returned; payment_method is mastercard.

Example request

curl -X POST https://vexutopia.com/api/v1/payments \
  -H "X-API-Key: vex_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "25.00",
    "currency": "USD",
    "mastercard": true,
    "customer_email": "[email protected]",
    "return_url": "https://yoursite.com/pay/return?id={payment_id}&status={status}",
    "webhook_url": "https://yoursite.com/api/webhooks/vexutopia"
  }'

Passing customer_email skips the email step on the checkout, so the customer goes straight to entering their card.

Gift cards

Gift card checkout only works when the invoice matches a fixed USD face. Each face covers 90% of the face up to the face. A $14 invoice uses the $15 card. We do not stretch a $5 or $10 card over an $8 product, unless you turn on Accept the next smaller gift card (Settings → Payment Methods → Gift Card): checkout then offers the next smaller face when it is at most $5 short, and redeeming it completes the order at that face. More detail: Gift Card.

Pass gift_card_amount on POST /v1/payments to choose the face shown. If you omit it and the invoice already sits in a window, checkout picks that face. If you pass a face that does not cover the invoice, the create call returns 422 GIFT_CARD_AMOUNT_MISMATCH. If the usual listing on the default store is sold out, checkout opens another in-stock listing on that store for the same face, then the other store if every listing there is gone. The tile stays hidden when neither store has stock.

Gift Card is on by default. Hide it from Settings. It is hosted checkout only. Other methods still appear. The session stays pending until the 16-character activation codes the customer pastes cover the invoice (a code worth less is credited and the customer is asked for the rest). Completing that fires payment.completed with payment_method: "gift_card". Credit is the invoice, not the card face. Fee is 14% + $1, T+1. You can request one Gift Card payout per day.

Cash App

US customers pay a Lightning invoice from Cash App or any Lightning wallet. You are credited the invoice in USD. This is not Cash App Pay and not an on-chain Bitcoin address. On by default; hide it from Settings. More detail: Cash App.

Completing fires payment.completed with payment_method: "cashapp" and processor: "lightning". Fee is 7%, T+0. $3 minimum. New York Cash App accounts may not be able to pay.

Indonesia & Philippines

Create the payment in IDR or PHP and send the customer to checkout_url. Hosted checkout shows QRIS in Indonesia and GCash / Maya in the Philippines when the region matches. Fee is 10% all-in, same-day settlement (T+0). Your site needs regional payments approval. These rails are not available with direct: true — see Direct Integration.

• Indonesia — QRIS, IDR 10,000–10,000,000. Pass customer_phone as a local mobile in 628… form. An IDR create without it returns 422 CUSTOMER_PHONE_REQUIRED. Hosted USD checkout still collects the number when the customer picks QRIS.
• Philippines — GCASH or MAYA, PHP 100–50,000. PHP without payment_method defaults to GCash. Pass customer_phone (local mobile in 639… form), customer_email and customer_name (first and last name). A PHP create without a phone returns 422 CUSTOMER_PHONE_REQUIRED, without an email 422 CUSTOMER_EMAIL_REQUIRED. Hosted USD checkout asks the customer for whichever of these you did not send.
• Amounts outside those windows return 422 AMOUNT_OUT_OF_RANGE.
• Webhooks use payment_method qris, gcash, or maya. Same child-transaction correlation as other regional rails.

Example — QRIS

curl -X POST https://vexutopia.com/api/v1/payments \
  -H "X-API-Key: vex_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "150000",
    "currency": "IDR",
    "payment_method": "QRIS",
    "customer_phone": "6281234567890",
    "return_url": "https://yoursite.com/order/success",
    "webhook_url": "https://yoursite.com/api/webhooks/vexutopia"
  }'

Example — GCash

curl -X POST https://vexutopia.com/api/v1/payments \
  -H "X-API-Key: vex_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "500",
    "currency": "PHP",
    "payment_method": "GCASH",
    "return_url": "https://yoursite.com/order/success",
    "webhook_url": "https://yoursite.com/api/webhooks/vexutopia"
  }'

Telegram Stars (optional)

Telegram Stars can be offered in two ways. Both require a LIVE API key and Telegram Stars enabled under Dashboard → Settings (off by default).

Mixed checkout still prices in USD and ceil-converts to stars when the customer picks Stars. The standalone endpoint accepts currency: "XTR" with a whole-star amount (e.g. 1500) when you need an exact pack, or currency: "USD" as before. The customer is charged the integer star count on the invoice — no KYC, no minimum, works worldwide. If they don't have enough Stars, Telegram prompts them to buy more inside the app.

curl -X POST https://vexutopia.com/api/v1/payments/telegram-stars \
  -H "X-API-Key: vex_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "1500",
    "currency": "XTR",
    "return_url": "https://yoursite.com/order/success"
  }'

{
  "id": "tx_…",
  "status": "pending",
  "checkout_url": "https://vexutopia.com/pay?session=tx_…",
  "telegram_invoice_url": "https://t.me/$…",
  "expires_at": "2026-04-09T19:32:10.977Z",
  "amount": "1500",
  "currency": "XTR",
  "stars": 1500,
  "created_at": "2026-04-09T18:32:10.710Z"
}

{
  "event": "payment.completed",
  "id": "tx_…",
  "status": "completed",
  "amount": "100",
  "currency": "XTR",
  "timestamp": "2026-04-09T20:13:36.280Z"
}

{
  "event": "payment.refunded",
  "id": "tx_…",
  "status": "refunded",
  "amount": "100",
  "currency": "XTR",
  "timestamp": "2026-04-09T20:45:11.000Z"
}

Retrieve a Payment

curl https://vexutopia.com/api/v1/payments/tx_b84050910b493a1e \
  -H "X-API-Key: vex_test_your_api_key"

{
  "id": "tx_b84050910b493a1e",
  "status": "completed",
  "amount": "20",
  "currency": "USD",
  "checkout_url": "https://checkout.vexutopia.com/pay?session=tx_b84050910b493a1e",
  "return_url": "https://yoursite.com/order/success",
  "provider": "card",
  "customer_email": "[email protected]",
  "customer_name": null,
  "failure_reason": null,
  "metadata": { "order_id": "1234" },
  "created_at": "2026-04-06T20:16:47.932Z",
  "updated_at": "2026-04-06T20:17:05.000Z",
  "expires_at": "2026-04-07T20:16:49.470Z",
  "completed_at": "2026-04-06T20:17:05.000Z"
}

Resend Webhook

Use this to recover from missed or failed webhook deliveries. The endpoint re-sends the payment.completed event to all your registered webhook endpoints and the webhook_url set at payment creation. Your handler should be idempotent — duplicate deliveries for an already-fulfilled payment should be a no-op on your side.

curl -X POST https://vexutopia.com/api/v1/payments/tx_b84050910b493a1e/resend-webhook \
  -H "X-API-Key: vex_live_your_api_key"

{
  "ok": true,
  "transaction_id": "tx_b84050910b493a1e",
  "event": "payment.completed"
}

Payment Statuses

Idempotency

Send an Idempotency-Key header on POST /v1/payments to make retries safe. If your service double-fires the same request (network retry, double-click, two tabs), reusing the same key returns the original response instead of creating a second payment session.

• Generate a unique key per logical payment intent (a UUID is fine). Format: A-Z a-z 0-9 _ -, 1–255 chars.
• Keys are scoped per API key and remembered for 24 hours.
• Same key + identical body within 24h → original response replayed, with header Idempotent-Replayed: true.
• Same key + different body → 409 IDEMPOTENCY_KEY_REUSED. Use a fresh key for new requests.
• Server errors (5xx) are not cached, so a retry with the same key will be processed normally.
• The header is optional — requests without it behave exactly as before.

Example

curl -X POST https://vexutopia.com/api/v1/payments \
  -H "X-API-Key: vex_test_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8b1f2c4e-9d3a-4f7b-8c1d-2e3f4a5b6c7d" \
  -d '{
    "amount": "20.00",
    "currency": "USD",
    "return_url": "https://yoursite.com/order/success"
  }'

Regional payments: correlating the webhook to your original payment

When a customer pays via a regional rail (PIX in Brazil, C2C in Argentina, SBP in Russia, QRIS in Indonesia, GCash or Maya in the Philippines), we settle the payment on a child transaction with its own ID. The original transaction we returned from POST /v1/payments is moved to CANCELLED with the reason “Superseded by [rail] regional payment”, and the payment.completed webhook is fired against the child.

To credit the customer in your system, correlate by payment_id (the original ID we returned to you) or by metadata.<your_field> if you passed one through.

Webhook payload (excerpt)

{
  "event": "payment.completed",
  "id": "tx_9fbd2dd90d27c04b",          // child tx (the regional settlement)
  "payment_id": "tx_68ede60fcaf92e24",   // original tx returned by POST /v1/payments
  "status": "completed",
  "amount": "98.47",
  "currency": "BRL",
  "processor": "regional",
  "payment_method": "pix",
  "settled_via": { "rail": "PIX", "amount": "98.47", "currency": "BRL" },
  "metadata": { "order_id": "1234" },
  "timestamp": "2026-05-08T01:33:43.656Z"
}

The same pattern applies if you also call GET /v1/payments/:id against the original ID — once the child has settled, the parent reflects status CANCELLED (superseded). Always trust the webhook's payment_id field as the authoritative back-reference.

Error Handling

All errors follow a consistent format:

{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE"
}

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": {
    "fieldErrors": {
      "amount": ["Invalid input: expected string, received number"]
    }
  }
}

{
  "error": "USDC wallet not configured. Set your payout wallet in Settings.",
  "code": "WALLET_NOT_CONFIGURED"
}

See the Errors reference for a complete list.