Introduction#
Gateway Async API (API v5) processes payments asynchronously: a request is accepted at once, the result is available later via a status request.
All requests: method POST, body application/json.
Each request is signed with X-JWS-Signature (see below).
URLs and methods#
The API has three URLs. The operation is selected by the X-Action header.| URL | X-Action | Method |
|---|
{domain}/v5/g2g/create | gateway.payment.create | Create payment |
{domain}/v5/g2g/read | gateway.payment.status | Get payment status |
{domain}/v5/g2g/read | gateway.request.status | Get request result |
{domain}/v5/g2g/edit | gateway.payment.clearing | Capture payment (clearing) |
{domain}/v5/g2g/edit | gateway.payment.reverse | Cancel payment (reverse) |
{domain}/v5/g2g/edit | gateway.payment.refund | Refund payment |
| Header | Required | Description |
|---|
Content-Type | yes | Always application/json. |
X-Action | yes | Invoked method, see the table above. |
X-Request-Id | yes | Unique request ID (UUID). Use a new value for every new operation. |
X-JWS-Signature | yes | Request signature. |
Accept | no | The response is always JSON. |
| Header | Description |
|---|
X-Request-Id | Equals X-Request-Id from the request. |
X-Request-Status | success — the request is processed, check the body; process — the result is not ready yet, the body is empty ({}), repeat the request later; error — the request is rejected. |
X-Datetime | Response date and time. |
Asynchronous processing#
Create payment, clearing, reverse and refund return status process (or process_clearing) at once. Get the final status via Get payment status.
A response can be empty {} with X-Request-Status: process: the data is being prepared, repeat the request in a few seconds.
If a response is lost, get it via Get request result with the X-Request-Id of that request.
A repeated request with the same X-Request-Id does not repeat the operation: the current state is returned.
X-JWS-Signature#
The signature is a detached JWS (RFC 7515, appendix F): BASE64URL(header) + .. + BASE64URL(signature). The payload is not included in the header value.Header (all fields are required):| Field | Value |
|---|
alg | HS256 |
auth_id | Your API user ID. |
uri | Path of the called URL, for example /v5/g2g/create. |
method | POST |
params | Empty string "". |
Signature: HMAC-SHA256 with your secret key over BASE64URL(header) + "." + BASE64URL(body).
BASE64URL — base64url without = padding.Sign exactly the bytes of the body you send. Any change after signing (formatting, spaces, key order) makes the signature invalid: 401, code 9998.
123456):{"uri":"/v5/g2g/create","auth_id":"123456","method":"POST","params":"","alg":"HS256"}
{"amount":100.5,"currency":"KZT","description":"Order #1001","order_id":"order_1001","auto_clearing":false,"from":{"type":"card","card":{"name":"IVAN IVANOV","pan":"4716047261941981","cvc":"123","year":30,"month":12}}}
eyJ1cmkiOiIvdjUvZzJnL2NyZWF0ZSIsImF1dGhfaWQiOiIxMjM0NTYiLCJtZXRob2QiOiJQT1NUIiwicGFyYW1zIjoiIiwiYWxnIjoiSFMyNTYifQ..gn0QR9q7rs21dA7rdgaA5XB5ACsHF6nX7dgf0jY5hrI
Errors#
| HTTP | Body | When |
|---|
| 200 | payment with status: error and error | The operation was rejected by business rules or by the bank (create, reverse, refund). |
| 400 | {"status": "error", "error": {...}} | Clearing rejected by business rules. |
| 400 | {"error": {"code": "9400", ...}} | The body is not valid JSON. |
| 401 | {"error": {"code": "9998", ...}} | Invalid signature. |
| 422 | {"error": {"code": "9403", ...}} | Validation error: a required header or field is missing or invalid. |
| 500 | {"error": {"code": "9999" or "10000", ...}} | Internal error. Repeat the request later with the same X-Request-Id. |
Error codes of each method are listed in its responses.