Create Invoice Method

This method creates a payment invoice and returns its identifier and payment URL.

RPC: invoice.v1.PubInvoiceService/CreateInvoice

---

TIP

Fields inside url_config (hook_url, fail_url, success_url) are optional.
external_id and payment_method_id are also optional.
metadata is a free-form struct (JSON object) and will be stored along with the invoice.

Request Example

curl

curl 'https://api.ibuy.exchange/invoice.v1.PubInvoiceService/CreateInvoice'   --header 'Authorization: Bearer <token>'   --header 'Content-Type: application/json'   --data '{
    "external_id": "inv-ext-001",
    "amount": "1499.00",
    "url_config": {
      "hook_url": "https://example.com/hooks/invoices",
      "fail_url": "https://example.com/pay/fail",
      "success_url": "https://example.com/pay/success"
    },
    "metadata": {
      "user_id": "user_42",
      "cart_id": "cart_777",
      "promo": "WELCOME10"
    },
    "payment_method_id": "pm_123"
  }'

typescript

import { createClient } from "@connectrpc/connect";
import { ibuy } from "@ibuy.exchange/api";

const invoiceService = createClient(ibuy.invoicev1.PubInvoiceService, transport);

const response = await invoiceService.createInvoice({
  externalId: "inv-ext-001",
  amount: "1499.00",
  urlConfig: {
    hookUrl: "https://example.com/hooks/invoices",
    failUrl: "https://example.com/pay/fail",
    successUrl: "https://example.com/pay/success",
  },
  metadata: {
    user_id: "user_42",
    cart_id: "cart_777",
    promo: "WELCOME10",
  },
  paymentMethodId: "pm_123",
});

console.log(response.id, response.paymentUrl);

Response Example

{
  "id": "inv_7f4b3b2c",
  "user_id": "usr_12345",
  "external_id": "inv-ext-001",
  "payment_url": "https://pay.ibuy.exchange/i/inv_7f4b3b2c",
  "amount": "1499.00",
  "expires_at": "2025-12-31T23:59:59Z"
}