Skip to main content

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 clientValue
base_urlhttps://api.peso.fast/pgc
merchant_tokenthe cash desk key, for example shp_01M4…
secret_keythe cash desk secret
Webhook URLunchanged 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>.

CallNotes
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}/cancel204 while the order waits for payment, 400 otherwise.
POST /api/v1/transactions/{id}/attachreceipts files, multipart. Accepted on a closed order; it opens an appeal with the receipt.
GET /api/v1/transactions/?type=inpage_number, page_size, merchant_transaction_id. ?type=out lists payouts.
POST /api/v1/transactions/payout-cardA payout to a card: amount, currency, card_number, owner_name, merchant_transaction_id.
POST /api/v1/transactions/payout-sbpA payout by SBP: phone_number, bank_name, owner_name, plus the same.
GET /api/v1/balanceYour 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.

SlugRail
card, internal-cardCard transfer (C2c)
sbp, internal-sbpSBP (Sbp)
accountBank account (Counterparty cash desk)
simMobile commerce (Phone)
qrNSPK 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-humoUZCARD / 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​

StatusMeaning here
processWaiting for payment, or paid and being confirmed
paidCredited to your balance
expiredThe customer did not pay in time
cancelCancelled 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.