API Documentation

Appearance

Introduction ​

The Wirekassa Public Payment API enables secure server-to-server communication with systems such as online stores, billing platforms, and third-party services.
It provides endpoints to create and retrieve transactions.

All requests must be signed using an api_key and secret_key with HMAC-SHA256, ensuring authenticity and data integrity.
This guide is intended for developers integrating their backends with the API.

1. Workflow Overview ​

A standard integration flow consists of these steps:

Step 1. Authentication Headers ​

Every request must include:

  • X-API-Key → API key issued to the client
  • X-Timestamp → current Unix time in seconds
  • X-Signature → HMAC-SHA256 signature generated with the secret key

Signature rules:

  • GET: HMAC-SHA256(secret_key, timestamp + query_string)
  • POST: HMAC-SHA256(secret_key, timestamp + request_body)

⚠️ The timestamp must be within 10 minutes of the server time to prevent replay attacks.

Step 2. Constructing Requests ​

  • Base URL: https://api.wirekassa.com/api/
  • Methods supported:
    • GET → retrieve transaction data
    • POST → create new transaction
  • Request format:
    • For GET, add query parameters to the URL
    • For POST, include raw JSON in the request body
  • Headers: always include authentication headers; for POST, add Content-Type: application/json.

Step 3. Request and Response Format ​

All request bodies, response bodies and callback bodies are flat: there are no nested objects anywhere.

  • The amount is sent as two separate top-level fields, amount and currency.
  • payment_method / payout_method is a plain string holding the method type ("card", "sbp", "cross_border"), not an object.
  • Every field belonging to the method is sent at the top level of the body, next to amount and channel.
  • In responses and callbacks, the method details come back prefixed with the method field name, e.g. payment_method_card_mask, payment_method_state.
ConceptRequest field(s)Response field(s)
Amountamount, currencyamount, currency
Partially paid amount—received_amount
Payment method typepayment_method (string)payment_method (string)
Payment method fieldstop level, e.g. pan, phonepayment_method_<field>
Payout method typepayout_method (string)method (string)
Payout method fieldstop level, e.g. account_number—
Failure reason—error_code, error_message

TIP

Callbacks carry the same flat body as the payment info response, so a single parser covers both.

Any top-level key that is not one of the envelope fields (channel, amount, currency, payment_method / payout_method, external_id, reference_id, return_url, callback_url, lang) is treated as a field of the payment or payout method.

Step 4. Sending Requests ​

Example GET (curl) ​

bash
TIMESTAMP=$(date +%s)
QUERY="channel=550e8400-e29b-41d4-a716-446655440000&transaction_id=123e4567-e89b-12d3-a456-426614174000"
MESSAGE="${TIMESTAMP}${QUERY}"
SIGNATURE=$(echo -n "$MESSAGE" | openssl dgst -sha256 -hmac "user1_secret_key" | awk '{print $2}')

curl -X GET "https://api.wirekassa.com/api/v1/payment/?${QUERY}"   -H "X-API-Key: user1_api_key"   -H "X-Signature: $SIGNATURE"   -H "X-Timestamp: $TIMESTAMP"

Example POST (curl) ​

bash
TIMESTAMP=$(date +%s)
PAYLOAD='{"channel":"550e8400-e29b-41d4-a716-446655440000","amount":"100.00","currency":"RUB","payment_method":"card","external_id":"ORDER123"}'
MESSAGE="${TIMESTAMP}${PAYLOAD}"
SIGNATURE=$(echo -n "$MESSAGE" | openssl dgst -sha256 -hmac "user1_secret_key" | awk '{print $2}')

curl -X POST "https://api.wirekassa.com/api/v1/payment/"   -H "X-API-Key: user1_api_key"   -H "X-Signature: $SIGNATURE"   -H "X-Timestamp: $TIMESTAMP"   -H "Content-Type: application/json"   -d "$PAYLOAD"

Step 5. Handling Responses ​

  • 200 OK → success; JSON payload with transaction details
  • 201 Created → a payment was created (POST /v1/payment/, POST /v1/payment/confirm/)
  • 4xx → client-side issue (e.g. invalid parameters, malformed JSON)
  • 5xx → server-side error

Your backend should validate response codes, log failures, and retry when appropriate.

2. Data Exchange Pattern ​

The integration follows a simple request–response cycle:

  1. Client backend builds request with headers and payload
  2. Request is sent via HTTPS to the API
  3. API verifies authentication and processes data
  4. API returns JSON with status code

3. Transaction Statuses ​

Every payment and payout carries one of four statuses:

  • processing → the transaction was accepted and is being processed
  • completed → the transaction succeeded
  • failed → the transaction was declined; see error_code and error_message
  • mispaid → payments only; the payer sent a different amount than requested. See Mispaid status

Security Requirements ​

  • HMAC signatures → required for every request
  • Timestamp checks → requests older than 10 minutes are rejected
  • HTTPS enforced → plain HTTP connections are not allowed
  • IP allow list → optional per account; when enabled, requests from other addresses are rejected with 403

Known Limitations ​

  • Exact body signing: For POST requests, the JSON used in the signature must match the transmitted body exactly.
  • Key management: API keys are not automatically rotated. If a key is revoked or expired, new credentials must be issued via the integration chat.

© 2025 Wirekassa