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, payment_method_id and mode are also optional. metadata is a free-form struct (JSON object) and will be stored along with the invoice.

Test Mode

You can create invoices in test mode by passing "mode": "TEST" in the request. Test invoices use test requisites and do not affect your balance. This is useful for integration testing and development.

If mode is not provided, it defaults to "LIVE".

WARNING

Test invoices are not real payments. Do not use test mode in production.

NSPK QR Code Generation

DANGER

For now we do not generate QR codes for invoices even with generate_nspk_qr option set to true.

We will update this documentation once we support QR code generation.

INFO

We return nspk_url only if qr.generate option is set to true.

If we didn't manage to generate QR code, we will return an error instead.

NSPK QR code generation allows customers to pay via a payment link instead of entering the recipient's card details.

You can also specify a timeout for QR code generation. If the timeout is not provided, a default value of 4 seconds is used.

To set the timeout, use the qr.timeout field. The value must follow the protobuf Duration JSON mapping format.

Request Example

curl

curl 'https://api.ibuy.exchange/api/public/invoice.v1.PubInvoiceService/CreateInvoice' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "external_id": "inv-ext-001",
    "amount": "1499.00",
    "mode": "TEST",
    "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",
    "qr": {
      "generate": true,
      "timeout": "10s"
    }
  }'

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",
  mode: "TEST",
  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 (optional fields are marked with ?)

{
  "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",
  "sbp"?: {
    "holder_name": "Name of holder",
    "phone": "phone number",
    "account": "account number"
  },
  "card"?: {
    "holder_name": "Name of holder",
    "card_number": "card",
    "account": "account number"
  },
  "bank_transfer"?: {
    "holder_name": "Name of holder",
    "bik": "bik",
    "account": "account number"
  },
  "bank"?: {
    "id": "uuid v4",
    "code": "code",
    "name": "name of bank"
  },
  // It is a link to NSPK page
  "nspk_url"?: "url to nspk"
}

Errors

We are following the gRPC and HTTP error codes convention. In this method you usually want to handle the following errors:

• Temporary error while generating QR code. Please retry.
  • HTTP Code: 503
  • gRPC Code: Internal