PayGateCore-compatible API
If your software already talks to the PayGateCore Merchant API, you do not need to integrate again. Péso serves that API at a separate base URL: the same endpoints, the same request and response fields, the same error envelope, and webhooks signed the way your verifier already expects. Behind it every call is an ordinary order on an ordinary cash desk, so the cabinet, tariffs, limits and the payment page all apply.
What to change
| Setting in your client | Value |
|---|---|
base_url | https://api.peso.fast/pgc |
merchant_token | the cash desk key, for example shp_01M4… |
secret_key | the cash desk secret |
| Webhook URL | unchanged on your side; set it in the cash desk settings or send webhook_url per order |
Every request is then authenticated by its X-Signature: lowercase hex HMAC-SHA256 of the
request body plus the path with its query, keyed with secret_key. This is the same scheme as
the webhooks, and the path may be signed either as /pgc/api/v1/… or as /api/v1/…. A client
that does not sign its requests can send <cash desk key>:<cash desk secret> as the token
instead.
The key and the secret are shown once when the cash desk is created, and the secret can be rotated in the cabinet. Rotation invalidates the old secret at once. Nothing else in your code changes.
Endpoints
All paths are relative to the base URL above and take Authorization: Bearer <merchant_token>.
| Call | Notes |
|---|---|
POST /api/v1/transactions/{method} | amount (whole units, string), currency, merchant_transaction_id, optional webhook_url, return_url. |
GET /api/v1/transactions/{id} | By our id or by your merchant_transaction_id. |
POST /api/v1/transactions/{id}/cancel | 204 while the order waits for payment, 400 otherwise. |
POST /api/v1/transactions/{id}/attach | receipts files, multipart. Accepted on a closed order; it opens an appeal with the receipt. |
GET /api/v1/transactions/?type=in | page_number, page_size, merchant_transaction_id. ?type=out lists payouts. |
POST /api/v1/transactions/payout-card | A payout to a card: amount, currency, card_number, owner_name, merchant_transaction_id. |
POST /api/v1/transactions/payout-sbp | A payout by SBP: phone_number, bank_name, owner_name, plus the same. |
GET /api/v1/balance | Your balance in USD and the rouble rate. |
GET /api/v1/limits/{currency} | The cash desk's bounds per method, in that currency. |
Methods
The {method} slug selects a rail within the cash desk's product line. A slug the cash desk
cannot serve answers 422 with payment_method: The payment method is not enabled.
| Slug | Rail |
|---|---|
card, internal-card | Card transfer (C2c) |
sbp, internal-sbp | SBP (Sbp) |
account | Bank account (Counterparty cash desk) |
sim | Mobile commerce (Phone) |
qr | NSPK QR |
transgran-card, transgran-card-tbank, -sber, -alfa, … | Cross-border card: UZCARD, HUMO or card, with the payer's bank pinned |
transgran-sbp, transgran-sbp-tbank, … | Cross-border phone transfer |
card-uzcard, card-humo | UZCARD / HUMO in UZS |
Response
{
"id": "ord_01M4FFFEANRNTSR5YF1CW4BK62",
"merchant_transaction_id": "55a587e6-c0c9-496b-827d-dcdfb1bc2a28",
"expires_at": "2026-10-09T04:56:52Z",
"amount": "3200",
"currency": "RUB",
"currency_rate": "94.66",
"amount_in_usd": "33.80",
"rate": "6.0000",
"commission": "2.03",
"card_number": "2200 1234 5678 9010",
"owner_name": "Ivan Testov",
"bank_name": "Sberbank",
"country_name": "РФ",
"payment_link": "https://peso.fast/payment/ord_01M4FFFEANRNTSR5YF1CW4BK62"
}
id is a string, not a number. currency_rate is units of your currency per USD with the
platform spread included; rate is the tariff percentage and commission the fee in USD, both
quoted at creation. payment_link opens Péso's payment page.
Statuses
| Status | Meaning here |
|---|---|
process | Waiting for payment, or paid and being confirmed |
paid | Credited to your balance |
expired | The customer did not pay in time |
cancel | Cancelled by you |
underpaid, overpaid and chargeback never occur: Péso credits exact amounts only, and a
transfer that does not match goes to an operator instead of to your balance.
Webhook
Posted to your webhook URL on every status change, with Authorization: Bearer <merchant_token>
and X-Signature = lowercase hex HMAC-SHA256 of body + path(+query) of your webhook URL,
keyed with secret_key. This is exactly PayGateCore's scheme, so your verifier works unchanged.
{
"id": "ord_01M4FFFEANRNTSR5YF1CW4BK62",
"merchant_transaction_id": "55a587e6-c0c9-496b-827d-dcdfb1bc2a28",
"type": "in",
"amount": "3200",
"paid_amount": "3200",
"currency": "RUB",
"currency_rate": "94.66",
"amount_in_usd": "33.80",
"status": "paid"
}
Answer 2xx; anything else is retried. paid_amount equals amount on paid and is 0 otherwise.
Errors
{ "code": 422, "message": "Validation error", "errors": { "amount": ["…"] } }
401 {"message":"Unauthorised"} for a wrong token, 400 {"code":409, …} for a duplicate
merchant_transaction_id, 500 {"code":1,"message":"Unable to get requisites."} when no
provider can take the order right now (retry later).
Payouts
payout-card and payout-sbp answer as PayGateCore does: id, merchant_transaction_id,
expires_at (when the provider is expected to have reported), amount, currency,
currency_rate, amount_in_usd, rate, commission. GET /api/v1/transactions/{id} shows a
payout with type: "out" and statuses new, process, paid, cancel; the card or phone comes
back masked. The webhook is the usual one with type: "out": paid when the customer was paid,
cancel when the payout failed and its debit returned to your balance.
payout-account and payout-sim are not available yet and answer 422 payment_method. Payouts
need to be enabled on the cash desk by support; the money rules are the same as for
gateway payouts.