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"

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.

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.

REFUNDEDYesA refund has been issued against this payment.

Status transitions

INITIATED → AUTHORIZED → COMPLETED
INITIATED → AUTHORIZATION_FAILED
INITIATED → EXPIRED
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.

Create Refund

Initiates a refund against a previously completed payment. Call this endpoint from your server only. The refund result arrives asynchronously via webhook.

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

Field	Type	Description
originalPaymentReferencerequired	string	Your `paymentReference` of the original payment to be refunded. The payment must be in status `COMPLETED` or `PARTIALLY_REFUNDED`.
refundReferencerequired	string	Your unique identifier for this refund request. Must be globally unique — submitting the same value twice is rejected.
amountrequired	number	Amount to refund in the payment's currency (RUB). Must not exceed the remaining refundable balance: `original amount − sum of non-failed refunds`.

⚠️ Refunds are not idempotent by reference — each refundReference must be unique. Reusing an existing reference returns an error even if the original refund failed.

Returns immediately with status INITIATED. The final outcome (COMPLETED or FAILED) arrives via webhook.

JSON · 200 OK

{
  "refundReference": "ref_456"
}

Error cases

Condition Result

refundReference already existsRejected — duplicate reference

Payment not foundRejected — unknown payment reference

Payment status not COMPLETED / PARTIALLY_REFUNDEDRejected — payment not eligible for refund

amount exceeds remainingRejected — refund amount exceeds refundable balance

JSON — Request body

{
  "originalPaymentReference": "pay_123",
  "refundReference":         "ref_456",
  "amount":                   500.00
}

JSON — Response 200 OK

{
  "refundReference": "ref_456"
}

Get Refund

Returns the current status of a refund by its reference. Use this to poll status if you have not yet received the webhook, or to reconcile refund state.

GET /v1/refunds/:reference

Path parameter :reference is your refundReference as provided when creating the refund.

JSON · 200 OK

{
  "refundReference": "ref_456",
  "status":          "INITIATED"
}

Field	Type	Description
refundReference	string	Your refund identifier, as provided at creation.
status	string	Current refund status: `INITIATED`, `COMPLETED`, or `FAILED`. See Refund Statuses.

ℹ️ Prefer the webhook for real-time updates. Use polling only as a fallback, for example to handle missed deliveries.

Refund Webhook Events

When a refund reaches a terminal status, BRICS Pay sends a REFUND_STATUS_UPDATE event to the webhookUrl configured for your merchant account.

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

REFUND_STATUS_UPDATE

Fired when a refund transitions to COMPLETED or FAILED. Use webhookData.reference to match the event to your refund record.

JSON — Payload

{
  "webhookId":   "550e8400-e29b-41d4-a716-446655440001",
  "webhookType": "REFUND_STATUS_UPDATE",
  "webhookData": {
    "reference": "ref_456",  // your refundReference
    "status":    "COMPLETED"
  }
}

Payload fields

Field	Type	Description
webhookId	string (UUID)	Unique identifier for this webhook delivery. Use for deduplication.
webhookType	string	Always `"REFUND_STATUS_UPDATE"`.
webhookData.reference	string	Your `refundReference` as supplied when creating the refund.
webhookData.status	string	Terminal refund status: `COMPLETED` or `FAILED`.

ℹ️ Refund and payment webhooks share the same endpoint (POST /webhooks/invoice-status) and are distinguished by the presence of refundRequestId in the provider payload. Use webhookId as a deduplication key.

Refund Statuses

A refund always starts as INITIATED. The terminal status arrives asynchronously via webhook once the provider has processed the request.

Refund status lifecycle

Status Terminal? Meaning

INITIATEDNoRefund request accepted and forwarded to the provider. Awaiting confirmation.

COMPLETEDYesRefund successfully processed. Funds will be returned to the customer.

FAILEDYesRefund rejected by the provider. No funds were returned. A new refund can be initiated.

Refund transitions

INITIATED → COMPLETED
INITIATED → FAILED

Effect on payment status

A successful refund updates the originating payment's status based on the remaining refundable balance.

Condition after refund New payment status

Refunded amount < original amountPARTIALLY_REFUNDED

Refunded amount = original amount (remaining = 0)REFUNDED

Payment transitions

COMPLETED → PARTIALLY_REFUNDED → REFUNDED
COMPLETED → REFUNDED (full refund in one request)

Refund Flow

End-to-end sequence from refund request to merchant notification.

1

Your server

Create the refund

Call POST /v1/refunds/create with originalPaymentReference, a unique refundReference, and the amount. BRICS Pay validates eligibility and immediately responds with {"refundReference": "..."}.

2

BRICS Pay → Provider

Forward to the provider

BRICS Pay saves the refund with status INITIATED and calls the provider's POST /api/v4/payments/refund. The provider returns a refundRequestId used to correlate the webhook.

3

Provider → BRICS Pay

Provider webhook

The provider posts the outcome to POST /webhooks/invoice-status. BRICS Pay identifies it as a refund event via refundRequestId and transitions the refund to COMPLETED or FAILED. The originating payment status is updated accordingly.

4

BRICS Pay → Your server

Merchant webhook

BRICS Pay posts a REFUND_STATUS_UPDATE event to your webhookUrl. Verify webhookData.status === "COMPLETED" and update your order accordingly. Respond 2xx to acknowledge.

ℹ️ A FAILED refund does not block you from initiating another refund for the same payment — as long as the payment is still in an eligible status and a new unique refundReference is used.