Create your first payment order

What you’ll build

In this quickstart, you will create a payment order that supports multiple payment rails, including crypto deposits and Orbi Pay.

Your customers will be able to:

• Pay with cryptocurrencies such as USDT, USDC, BTC, and ETH
• Use Orbi Pay for instant payments
• Complete payments through a unified checkout flow

Before you begin

Make sure you have:

• An active Orbi One account
• A Sandbox API key
• Node.js installed in your development environment

Step 1 — Set up authentication

All API requests must be authenticated using the x-api-key header.

Store your API key securely and never expose it in client-side code.

import axios from "axios";

const API_BASE_URL = "https://sandbox.gateway.orbipayments.com";
const API_KEY = process.env.ORBI_API_KEY;

const orbiClient = axios.create({
  baseURL: API_BASE_URL,
  headers: {
    "Content-Type": "application/json",
    "x-api-key": API_KEY,
  },
});

Step 2 — Create a payment order

Create an order by defining the items, accepted payment rails, and payment configuration.

const createPaymentOrder = async () => {
  const response = await orbiClient.post("/v1/orders", {
    external_reference_id: "order_123",
    items: [
      {
        name: "Pepperoni pizza",
        quantity: 1,
        unit_price: "259",
        currency: "MXN",
        modifiers: [
          {
            name: "Extra cheese",
            quantity: 1,
            unit_price: "25",
            currency: "MXN",
          },
        ],
      },
    ],
    payment_currency: "USDT",
    enable_rails: ["orbi_pay", "crypto_deposit"],
    capabilities: {
      can_cancel: true,
      can_update: false,
      can_overpay: false,
      partial_payments: true,
      express_checkout: false,
      expiration_auto_renewal: false,
    },
    expiration_minutes: 60,
    metadata: {
      customer_id: "cust_123",
      env: "sandbox",
    },
  });

  return response.data;
};

createPaymentOrder().then((order) => {
  console.log("Order created:", order.id);
});

Step 3 — Understand the response

A successful request returns an order object similar to the following:

{
  "id": "ord_01KCKYJWGX90AVAPFP2R481RAW",
  "status": "awaiting_payment",
  "currency": "USDT",
  "total_amount": "15.516946",
  "remaining_amount": "15.516946",
  "rates": {
    "MXN_USDT": "0.054637"
  },
  "deposit_instructions": [
    {
      "method": "orbi_pay",
      "details": {
        "orbi_id": "I698263"
      }
    },
    {
      "method": "crypto_deposit",
      "details": {
        "currency_name": "USDt Tether",
        "deposit_addresses": [
          {
            "address": "0xB813E983b571103C67a1d17B9d54F8921aae6f79",
            "network": "Binance Smart Chain Testnet"
          }
        ]
      }
    }
  ],
  "expiration_date": "2025-12-16T16:11:09.181Z"
}

Key fields

• id — Unique identifier for the order
• status — Current order status (awaiting_payment, paid, expired)
• total_amount — Total amount to be paid in the selected payment currency
• remaining_amount — Amount remaining to complete the order
• deposit_instructions — Payment methods and instructions available to the customer
• expiration_date — Time at which the order expires

Step 4 — Monitor payment status

You can retrieve the order at any time to check its status.

const getOrder = async (orderId) => {
  const response = await orbiClient.get(`/v1/orders/${orderId}`);
  return response.data;
};

getOrder("ord_01KCKYJWGX90AVAPFP2R481RAW").then((order) => {
  console.log(order.status);
});

Step 5 — Receive real-time updates (recommended)

For production integrations, Orbi strongly recommends using webhooks to receive real-time updates when an order or payment status changes.

Webhook events notify your backend when:

• An order is updated or paid
• A payment is applied or fails
• A refund is issued

See Configure webhooks for setup instructions.

Testing your integration

In the Sandbox environment, you can test:

• Orders using orbi_pay
• Crypto deposits using test networks
• Currency conversion between fiat and crypto
• Order expiration behavior

Sandbox payments do not represent real value.

Next steps

Now that you’ve created your first payment order, you can:

• Configure webhooks for real-time notifications
• Implement a checkout or express checkout flow
• Explore advanced order capabilities
• Prepare your integration for production

For full details, see the API Reference.