Direct Integration

Skip checkout.vexutopia.com entirely. With direct: true, the response from POST /v1/payments is a Vexutopia-hosted payment page on the apex domain — you redirect your customer there from your own site (or open it in a popup, or anywhere else you choose).

Direct integration is a redirect-target change only. Webhooks, status polling, fees, rolling reserve and partner attribution behave identically to the hosted flow.

When to use Direct vs. Hosted

Use the hosted page

You want customers to choose between several methods
You want our trust badges, brand polish, and method discovery
You don't want to manage redirects yourself

Use direct integration

You already have your own checkout UI
The customer has already chosen a method (e.g. a “Pay with PIX” button on your page)
You want to keep the customer on your domain until the redirect

Eligibility

Direct integration is gated by the same per-Site approval as the hosted flow. To use it you need:

An active Vexutopia merchant account with at least one approved Site.
Regional payments approval for the Site you're creating the transaction under. Request it from the Settings page in your dashboard. Without approval, requests with direct: true return 422 NO_PROVIDER_AVAILABLE.
A LIVE API key (test keys can be used for integration but no real funds move).

Supported methods (v1)

Parameter	Type	Description
`PIX (BRL)`	regional	Brazil — local instant transfer. Customer scans a QR or pastes a copy-and-paste code on the payment page.
`C2C (ARS)`	regional	Argentina — card-to-card.
`SBP (RUB)`	regional	Russia — Sistema Bystrykh Platezhei (Faster Payments System).

Crypto on-ramp, Telegram Stars, Indonesia (IDR / QRIS), and the Philippines (PHP / GCash / Maya) are not supported in direct mode. Use hosted checkout for those rails. IDR or PHP with direct: true returns 422 DIRECT_MODE_UNSUPPORTED_CURRENCY.

Request

The endpoint and authentication are identical to the hosted flow — only the direct: true field is new. See POST /v1/payments for the full parameter list.

Body parameters used by direct mode

Parameter	Type	Description
`amount`required	string	Decimal amount as a string — e.g. "100.00". Not cents.
`currency`required	string	Three-letter ISO. Direct mode (v1) accepts only BRL, ARS, RUB.
`return_url`required	string	Where the customer is sent back after payment (success or fail).
`customer_email`	string	Strongly recommended — used for payment receipts and reconciliation.
`webhook_url`	string	Where we POST status updates. Same shape as the hosted flow.
`metadata`	object	Custom key-value pairs (string values). Round-trips back on the webhook.
`direct`required	boolean	Set to true to receive the direct payment page URL (hosted on vexutopia.com) in the response.

Example — Direct PIX

cURL

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": "100.00",
    "currency": "BRL",
    "customer_email": "[email protected]",
    "return_url": "https://yoursite.com/order/123/return",
    "webhook_url": "https://yoursite.com/api/webhooks/vexutopia",
    "metadata": { "order_id": "1234" },
    "direct": true
  }'

Response

The shape is identical to the hosted flow. The key difference: checkout_url is a Vexutopia-hosted page on the apex domain (e.g. /pay/regional/...) that renders the local rail (PIX QR, C2C details, SBP redirect, etc.) — not checkout.vexutopia.com.

JSON

{
  "id": "tx_b84050910b493a1e",
  "status": "pending",
  "amount": "100.00",
  "currency": "BRL",
  "checkout_url": "https://vexutopia.com/pay/regional/tx_b84050910b493a1e",
  "expires_at": "2026-05-01T13:30:00Z"
}

Redirect your customer to checkout_url. They complete the payment on a page hosted by Vexutopia and are returned to your return_url with ?status=success or ?status=fail.

Webhooks

Webhook delivery is identical to the hosted flow. We send you a payment.completed / payment.failed / payment.cancelled event at your webhook_url once the payment reaches its final outcome. The HMAC signature, retry policy, and payload shape are the same — see Webhooks.

Errors specific to direct mode

Parameter	Type	Description
`DIRECT_MODE_UNSUPPORTED_CURRENCY`	422	You passed direct: true with a currency outside the v1 allowlist (BRL/ARS/RUB).
`NO_PROVIDER_AVAILABLE`	422	Your Site is not approved for regional payments. Request approval from the dashboard before retrying.
`WALLET_NOT_CONFIGURED`	400	Your organization has no payout wallet configured. Set it in Settings.
`VALIDATION_ERROR`	422	Body failed schema validation. Inspect details.fieldErrors for field-level messages.

Standard errors (auth, rate-limit, idempotency) behave identically to the hosted flow — see Error Codes.

Next Steps

Payments API — full parameter list and the hosted-checkout flow.
Webhooks — payload reference and signature verification.
Error Codes — complete list with retry guidance.