BRICS Pay E-com API Reference

Accept card and FPS (Faster Payment System) payments. Create an invoice server-side, redirect your customer to the hosted payment page, and receive real-time status updates via webhooks.

Base URL

https://<host>

Versioning

URI prefix — /v1/...

🔑

API Key

Pass your key in the x-api-key header on every server-to-server request

🛡️

IP Whitelist

Requests from non-whitelisted IPs are rejected before authentication

🔔

Webhooks

Status changes are pushed to your webhookUrl in real time

Authentication

All requests to POST /v1/payments/create require two layers of verification: an API key in the request header and your server's IP address in the whitelist.

API Key

Include your API key in the x-api-key header on every request.

HTTP

POST /v1/payments/create
x-api-key:     YOUR_API_KEY
Content-Type:  application/json

Header	Value
`x-api-key`	API key issued to you upon merchant registration.

IP Whitelist

Requests are additionally verified against the IP whitelist for your merchant account. Requests from unknown addresses are rejected regardless of API key validity.

⚠️ Your server's IP address must be added to the whitelist before going live. Contact your account manager to add or update whitelisted IPs.

ℹ️ The create endpoint is server-to-server only — never call it from browser or mobile client code. Your API key must remain secret at all times.

Idempotency

The create endpoint is safe to retry. Submitting the same paymentReference more than once will not create duplicate invoices or charges.

If a request with a given paymentReference has already been processed, BRICS Pay returns the original response — including the same invoicePageUrl — without creating a new invoice.

Scenario	Behaviour
First request with a `paymentReference`	Invoice is created. Returns `invoicePageUrl`.
Repeated request with the same `paymentReference`	No new invoice is created. Returns the original `invoicePageUrl`.
Request with a different `paymentReference`	A new, independent invoice is created.

ℹ️ Use a unique, stable identifier from your order management system — for example, your internal order ID — as the paymentReference. This makes retries after network failures safe without any additional coordination.

Create Invoice

Creates a payment invoice and returns a hosted payment page URL. Call this endpoint from your server only — never from the browser.

POST /v1/payments/create 🔑 API Key + IP Whitelist

Field	Type	Description
paymentReferencerequired	string	Your unique order identifier. Resubmitting the same value returns the existing invoice without creating a new one. See Idempotency.
methodrequired	string	Payment method: `"CARD"` or `"SBP"`.
currencyTickerrequired	string	Must be `"RUB"`.
returnUrloptional	string	Fallback redirect URL for any outcome when `successUrl` / `failUrl` are not set.
successUrloptional	string	Redirect URL after a successful payment. Overrides `returnUrl` on success.
failUrloptional	string	Redirect URL after a failed payment. Overrides `returnUrl` on failure.
client.billing.countryCoderequired	string	Payer's country code, ISO 3166-1 alpha-2. Example: `"RU"`.
client.billing.emailoptional	string	Payer's email address.
client.billing.phoneoptional	string	Payer's phone number.
client.billing.firstNameoptional	string	Payer's first name.
client.billing.lastNameoptional	string	Payer's last name.
productsrequired	array	Line items. At least one item required. Total charge = `sum(unitPrice × quantity)`.
products[].namerequired	string	Product or service name.
products[].skurequired	string	Product article / SKU in your system.
products[].unitPricerequired	number	Price per unit in RUB.
products[].quantityrequired	number	Number of units.

On success, returns a single URL to redirect your customer to. The invoice stays active until its configured time-to-live expires.

JSON · 200 OK

{
  "invoicePageUrl": "https://<host>/invoice/a1b2c3d4-e5f6-..."
}

ℹ️ Redirect your customer to invoicePageUrl immediately. Once the invoice expires its status changes to EXPIRED and payment can no longer be completed.

JSON — Request body

{
  "paymentReference": "order-12345",
  "method":           "CARD",
  "currencyTicker":   "RUB",
  "returnUrl":        "https://your-shop.com/return",
  "successUrl":       "https://your-shop.com/success",
  "failUrl":          "https://your-shop.com/fail",
  "client": {
    "billing": {
      "countryCode": "RU",
      "email":       "[email protected]",
      "phone":       "+79001234567",
      "firstName":   "Ivan",
      "lastName":    "Ivanov"
    }
  },
  "products": [
    {
      "name":      "Pro Subscription",
      "sku":       "sub-pro-1m",
      "unitPrice": 999.00,
      "quantity":  1
    }
  ]
}

Invoice Page

The hosted payment page served to your customer. Redirect the customer to invoicePageUrl and BRICS Pay handles the rest — no additional integration required.

GET /invoice/:id

Returns an HTML page for display in the customer's browser. Routing happens automatically when the customer follows invoicePageUrl.

The page adapts to the chosen payment method:

For CARD — a secure card entry form
For SBP — a button to open the customer's banking app

Page states by payment status

Status Page behaviour

INITIATEDPayment form is active. Countdown timer is running.

EXPIRED"This payment session has expired"

AUTHORIZED"This payment is already being processed"

COMPLETED"This payment has already been completed"

AUTHORIZATION_FAILED"Authorization failed for this payment"

REFUNDED"This payment has been refunded"

Get Payment Status

Returns the current status of a payment by your own order identifier. Use this as a fallback when a webhook has not been received within your expected timeframe.

GET /v1/payments/:reference 🔑 API Key

Path parameters

Parameter	Description
referencerequired	Your `paymentReference` as provided when creating the invoice.

JSON · 200 OK

{
  "paymentReference": "order-12345",
  "status":           "COMPLETED"
}

Possible values for status:

INITIATED AUTHORIZED AUTHORIZATION_FAILED COMPLETED PARTIALLY_REFUNDED REFUNDED EXPIRED

ℹ️ Prefer webhooks over polling for real-time status updates. Use this endpoint only as a fallback — for example, to verify status when a webhook delivery was missed or delayed.

Incoming Webhook Events

BRICS Pay sends a POST request to the webhookUrl configured for your merchant account whenever a payment status changes.

⚠️ Your endpoint must return a 2xx response. If it does not, the webhook status is set to ERROR. To trigger a retry, contact your administrator — automatic retries are not currently supported.

Request headers

Header	Description
`X-Signature`	HMAC-SHA256 signature of the raw request body, keyed with your `x-api-key`. Verify this on every incoming webhook to confirm it originated from BRICS Pay.

Node.js — Signature verification

import crypto from 'crypto';

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig      = req.headers['x-signature'];
  const expected = crypto
    .createHmac('sha256', process.env.BRICS_PAY_API_KEY)
    .update(req.body)   // raw Buffer, NOT parsed JSON
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  // handle event...
  res.sendStatus(200);
});

INVOICE_STATUS_UPDATE

Fired on every payment status transition. Use webhookData.reference to match the event to your internal order.

JSON — Payload

{
  "webhookId":   "550e8400-e29b-41d4-a716-446655440000",
  "webhookType": "INVOICE_STATUS_UPDATE",
  "webhookData": {
    "reference": "order-12345",  // your paymentReference
    "status":    "COMPLETED"
  }
}

Payload fields

Field	Type	Description
webhookId	string (UUID)	Unique identifier for this webhook delivery. Use for deduplication.
webhookType	string	Always `"INVOICE_STATUS_UPDATE"`.
webhookData.reference	string	Your `paymentReference` as supplied when creating the invoice.
webhookData.status	string	New payment status. See Payment Statuses.

ℹ️ Use webhookId as a deduplication key — store it and ignore any delivery that carries a webhookId you have already processed.

Payment Object

The logical representation of a payment in BRICS Pay. Fields from this object appear in webhook payloads and are referenced throughout this documentation.

Field	Type	Description
reference	string	Your unique order identifier, as provided in `paymentReference` at invoice creation.
status	string	Current payment status. See Payment Statuses.
method	string	Payment method: `"CARD"` or `"SBP"`.
currencyTicker	string	Always `"RUB"`.
amount	number	Total charge in RUB. Calculated as `sum(products[].unitPrice × quantity)`.
products	array	Line items as provided at invoice creation. Each item contains `name`, `sku`, `unitPrice`, and `quantity`.
client	object	Payer information as provided at invoice creation: `billing.countryCode`, `billing.email`, `billing.phone`, `billing.firstName`, `billing.lastName`.
invoicePageUrl	string	The hosted payment page URL. Valid until the invoice expires.
successUrl	string · null	Redirect URL on successful payment, as provided at creation.
failUrl	string · null	Redirect URL on failed payment, as provided at creation.
returnUrl	string · null	Fallback redirect URL, as provided at creation.

Payment Statuses

Every status change triggers a webhook. Only COMPLETED means funds were successfully collected.

Status Terminal? Meaning

INITIATEDNoInvoice created. Waiting for the customer to complete payment.

AUTHORIZEDNoPayment authorised by the provider and currently being processed.

COMPLETEDYesPayment successfully completed. Safe to fulfil the order.

AUTHORIZATION_FAILEDYesAuthorisation declined — invalid card details, bank refusal, etc. No funds moved.

EXPIREDYesInvoice TTL elapsed before the customer completed payment. No funds moved.

PARTIALLY_REFUNDEDNoOne or more partial refunds issued. Further refunds possible up to the remaining amount.

REFUNDEDYesA full refund has been issued against this payment.

Status transitions

INITIATED → AUTHORIZED → COMPLETED
INITIATED → AUTHORIZATION_FAILED
INITIATED → EXPIRED
COMPLETED → PARTIALLY_REFUNDED → REFUNDED
COMPLETED → REFUNDED

Typical Flow

End-to-end integration from invoice creation to order fulfilment.

1

Your server

Create the invoice

Call POST /v1/payments/create with order details. BRICS Pay returns invoicePageUrl.

2

Your server

Redirect the customer

Send the customer's browser to invoicePageUrl. BRICS Pay serves the hosted payment page.

3

Customer

Complete payment

The customer enters card details or confirms via their banking app. BRICS Pay processes the payment with the provider.

4

BRICS Pay → Your server

Receive the webhook

BRICS Pay posts an INVOICE_STATUS_UPDATE event to your webhookUrl with the new payment status.

5

Your server

Fulfil the order

Verify webhookData.status === "COMPLETED" and fulfil the order. Respond 2xx to acknowledge the webhook.

ℹ️ Always use the webhook as the authoritative signal for order fulfilment — do not rely on redirect URL parameters alone, as customers may close the browser before being redirected back to your site.