Quick start

Five steps from an empty account to a completed test order with a callback on your server. Nothing here needs approval: the sandbox provider takes every order, and you drive its outcome from the cabinet.

1. Create a cash desk

In the cabinet, open Cash desks and click Create cash desk. Four screens:

1. Method. Pick the payment method the customer will use and the rails to allow. This choice is permanent for the cash desk.
2. Name and callbacks. Name it, and enter the callback URL: the address on your server where we will POST order events. It can stay empty for now, but an order cannot be created without one, either on the cash desk or in the request.
3. Limits. Optional minimum and maximum order amount in USD.
4. Keys. The key and the secret, shown once.

PESO_SHOP_KEY=shp_01M1P932FS0FQPNM3T63KM2XAT
PESO_SHOP_SECRET=V-a6DTYT8HQ0LEbueHRem7KaB9jJ8TKF-0RWL5wxVUs

The key goes in a header on every request. The secret never leaves your server: it only signs. If you lose it, issue a new one from the cash desk card; the old one stops working immediately.

2. Sign a request

Every gateway call carries four headers, and the signature is an HMAC-SHA256 over the timestamp, a nonce, the method, the path and the body hash. Try it on GET /gw/v1/methods, which changes nothing and tells you what the cash desk can accept right now.

API=https://api.peso.fast
TS=$(date +%s)
NONCE=$(openssl rand -hex 8)
EMPTY=$(printf '' | openssl dgst -sha256 -hex | awk '{print $2}')
SIGN=$(printf '%s.%s.GET./gw/v1/methods.%s' "$TS" "$NONCE" "$EMPTY" \
       | openssl dgst -sha256 -hmac "$PESO_SHOP_SECRET" -hex | awk '{print $2}')

curl "$API/gw/v1/methods" \
  -H "X-Gate-Key: $PESO_SHOP_KEY" \
  -H "X-Gate-Ts: $TS" \
  -H "X-Gate-Nonce: $NONCE" \
  -H "X-Gate-Sign: $SIGN"

A 200 with a list of rails means the signature is right. A 401 AUTH_FAILED means the key or the algorithm is off: the Authentication page lists the usual causes.

3. Create an order

BODY='{"amount":5000.00,"currency":"RUB","rail":"Sbp","orderRef":"your-order-42"}'
TS=$(date +%s)
NONCE=$(openssl rand -hex 8)
HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $2}')
SIGN=$(printf '%s.%s.POST./gw/v1/orders.%s' "$TS" "$NONCE" "$HASH" \
       | openssl dgst -sha256 -hmac "$PESO_SHOP_SECRET" -hex | awk '{print $2}')

curl -X POST "$API/gw/v1/orders" \
  -H "X-Gate-Key: $PESO_SHOP_KEY" \
  -H "X-Gate-Ts: $TS" \
  -H "X-Gate-Nonce: $NONCE" \
  -H "X-Gate-Sign: $SIGN" \
  -H 'Content-Type: application/json' \
  -d "$BODY"

The 201 response carries the order id, the payment details and expiresAt. In the sandbox the details are placeholders: +70000000000 for SBP, 4111 1111 1111 1111 for card transfers.

4. Play the provider

Open the order in the cabinet: Orders, then the row. A sandbox order shows a Simulate payment button. Click it: the order becomes Completed, your balance grows by the credited amount, and within about ten seconds the callback worker POSTs order.completed to your callback URL. Simulate failure does the same with order.cancelled.

The What we sent you panel on the same page lists every delivery attempt with the HTTP code and the first characters of your server's response, so you can see whether your handler answered.

5. Receive the callback

Your handler should, in this order:

1. read the raw body before parsing it;
2. verify X-Gate-Sign against {X-Gate-Ts}.{X-Gate-Event-Id}.{body} with the cash desk secret;
3. drop the event if you have already processed its X-Gate-Event-Id;
4. update the order on your side;
5. answer 200.

Anything other than 200 makes us retry with growing delays, eight attempts in all. The Callbacks page has handler examples in several languages.

That is the whole integration. Before going live, walk through the checklist.