Developer Resources

API Documentation

Integrate OrvexPay's crypto payment infrastructure into your application with our robust REST API.

Run in Postman

Download Json

Need specialized help?

Contact our technical support team for custom integration solutions.

Contact Support

General Information

OrvexPay provides a RESTful API that allows you to accept cryptocurrency payments globally. All requests should be made to our base URL and use JSON for the request body. Responses are standard JSON objects.

Base URLhttps://api.orvexpay.com

Authentication

Public payment API calls (such as POST /api/invoice) are authenticated via a x-api-key header. You can create and manage API keys in the API Keys section of your merchant dashboard.

x-api-keyYOUR_API_KEY_HERE

Security Best Practice

Never share your API keys or commit them to public repositories. If a key is compromised, revoke it immediately and generate a new one from the API Keys page.

Dashboard endpoints (for example /api/merchant/*) use bearer authentication with the merchant's session token and are not intended for public client integrations.

Sandbox Testing & Payment Simulation

OrvexPay provides an isolated, risk-free **Sandbox** environment to test your integration without moving real assets on the blockchain. Sandbox invoices skip blockchain confirmation checks, do not count towards live revenue/balances, and ignore auto-sweep configurations.

1. Setup Sandbox Key

Go to the API Keys page and toggle a project's environment to **Sandbox**. Use the generated `SBX_` key in your SDK or API requests.

2. Simulate via Dashboard

In the Invoices list, click the green **"Simulate"** button next to any sandbox invoice in `Waiting` status to instantly mark it as paid.

3. Simulate via API Endpoint

You can programmatically confirm a sandbox invoice by sending an authenticated request to the simulation endpoint.

POST/api/invoice/{id}/sandbox/pay

Optional Body Schema:

{
  "amountReceived": 100.00, // Custom mock paid amount (defaults to invoice expected amount)
  "transactionHash": "sbx_mock_tx_hash_123" // Custom transaction hash
}

cURL Example:

curl -X POST "https://api.orvexpay.com/api/invoice/INVOICE_UUID_HERE/sandbox/pay" \
  -H "x-api-key: YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amountReceived": 25.50}'

4. Webhook Event Callback

Simulated payments trigger the same `invoice.paid` webhook event configured for the project, using production signing signatures. The callback payload contains an `"environment": "sandbox"` field:

{
  "invoiceId": "b9e2f8b7-4c41-4c0c-8f7f-4a1e9c2c9c01",
  "orderId": "ORDER-123",
  "status": "Paid",
  "amount": 25.50,
  "currency": "USDT",
  "environment": "sandbox"
}

1. Create Invoice

POST/api/invoice

Creates a new on-chain payment invoice for your customer. The response contains a unique invoice id, payment address and expected amount.

Request Body

Field	Type	Required
priceAmount	string (decimal as string, e.g. "100.00")	Yes
priceCurrency	string (fiat ISO code, e.g. "USD")	Yes
payCurrency	string (crypto code, e.g. "BTC")	Yes
successUrl	string (URL)	Yes
cancelUrl	string (URL)	Yes
orderId	string	No
orderDescription	string	No
isDonation	boolean	No

Example Request

curl -X POST "https://api.orvexpay.com/api/invoice" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "priceAmount": "100.00",
    "priceCurrency": "USD",
    "payCurrency": "BTC",
    "successUrl": "https://yourapp.com/payment/success",
    "cancelUrl": "https://yourapp.com/payment/cancel",
    "orderId": "ORDER-123",
    "orderDescription": "Premium Subscription"
  }'

Example Response

{
  "id": "b9e2f8b7-4c41-4c0c-8f7f-4a1e9c2c9c01",
  "orderId": "ORDER-123",
  "orderDescription": "Premium Subscription",
  "priceAmount": 100.00,
  "priceAmountInUsd": 3.45,
  "amountReceived": 0,
  "priceCurrency": "USD",
  "payCurrency": "BTC",
  "status": "Waiting",
  "createdAt": "2025-01-01T12:00:00Z",
  "expiredAt": "2025-01-01T12:30:00Z",
  "address": "bc1qxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "amountExpected": 0.0025,
  "successUrl": "https://yourapp.com/payment/success",
  "cancelUrl": "https://yourapp.com/payment/cancel",
  "projectName": "Your Project Name",
  "isDonation": false
}

Redirect Flow (Hosted Checkout)

The API itself returns JSON only. To mimic providers like PayTR and send the customer to a hosted payment page, you should redirect them to the OrvexPay checkout URL using the returned id:

// Example: client-side (SPA) redirect
const res = await fetch("https://api.orvexpay.com/api/invoice", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY_HERE",
  },
  body: JSON.stringify({
    priceAmount: "100.00",
    priceCurrency: "USD",
    payCurrency: "BTC",
    successUrl: "https://yourapp.com/payment/success",
    cancelUrl: "https://yourapp.com/payment/cancel",
  }),
});
const invoice = await res.json();
window.location.href = "https://orvexpay.com/pay/" + invoice.id;

// Example: server-side redirect (Node/Express)
app.post("/checkout", async (req, res) => {
  const apiRes = await fetch("https://api.orvexpay.com/api/invoice", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.VIREXPAY_API_KEY!,
    },
    body: JSON.stringify(req.body),
  });
  const invoice = await apiRes.json();
  return res.redirect(302, "https://orvexpay.com/pay/" + invoice.id);
});

2. Get Invoice Status

GET/api/invoice/{id}

Retrieve the current status and payment details of an existing invoice by its id. This endpoint returns the same shape as the create-invoice response.

GET https://api.orvexpay.com/api/invoice/{id}

3. Payout (Withdraw) API

Payout endpoints support both merchant JWT and x-api-key authentication. If you use API key auth, the request is automatically scoped to that key's project.

Available Endpoints

GET https://api.orvexpay.com/api/payout/balance

POST https://api.orvexpay.com/api/payout/request

POST https://api.orvexpay.com/api/payout/verify

GET https://api.orvexpay.com/api/payout/history

POST https://api.orvexpay.com/api/payout/{id}/cancel

POST /api/payout/request Request Body

Field	Type	Required
amount	number (max 8 decimals)	Yes
currency	string (e.g. "USDT", "BTC")	Yes
address	string (wallet address)	Yes
projectId	string (UUID)	No*
note	string (max 500 chars)	No

* When using x-api-key, projectId is auto-determined from API key scope.

Payout Request Example

curl -X POST "https://api.orvexpay.com/api/payout/request" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 125.50,
    "currency": "USDT",
    "address": "TRXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "note": "Kullanici: #4821 - Acil odeme",
    "projectId": "YOUR_PROJECT_API_KEY_ID"
  }'

Payout Response Example

{
  "id": "943f21c4-9412-4e8a-8682-e8f824f5ad23",
  "amount": 125.5,
  "currency": "USDT",
  "address": "TRXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "note": "Kullanici: #4821 - Acil odeme",
  "status": "AwaitingVerification",
  "transactionHash": null,
  "adminNote": null,
  "createdAt": "2026-04-16T10:15:20Z"
}