Payment API

Overview

The Payment API is a REST interface for backend integrations with the Wirekassa system.
It enables client applications (e.g. online stores, billing systems) to initiate payments and query transaction details.

Authentication is handled using api_key and secret_key with HMAC-SHA256 signatures.
This ensures all communication is secure and verified.

• Base URL: https://api.wirekassa.com/api/v1/payment/

All request and response bodies are flat — see Request and Response Format.

Authentication

Each request must include three headers:

• X-API-Key → client’s API key
• X-Timestamp → current Unix timestamp (seconds)
• X-Signature → HMAC-SHA256 signature generated with the secret key

How to calculate signatures:

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

⚠️ Requests older than 10 minutes compared to API server time will be rejected.

Endpoints

GET /v1/payment/

Use this endpoint to fetch transaction data.

Request:

• Method: GET
• Query parameters:
  • channel (UUID, required)
  • transaction_id (UUID, optional)
  • external_id (string, optional)
  • reference_id (string, optional)

👉 At least one of transaction_id, external_id or reference_id must be included.

Example (curl):

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"

Successful Response (200):

{
  "status": "processing",
  "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
  "amount": "111.0",
  "currency": "RUB",
  "redirect_url": "https://pay.wirekassa.com/123e4567-e89b-12d3-a456-426614174000/",
  "channel": "8fec39b6-c41b-46d6-b219-61d115fdfa2d",
  "external_id": "ORDER123",
  "payment_method": "card",
  "payment_method_card_mask": "411111****1111",
  "payment_method_cardholder": "S. Hopper",
  "payment_method_user_agent": "Mozilla/5.0 ...",
  "payment_method_user_ip": "203.0.113.42",
  "payment_method_bank_name": "Example Bank",
  "payment_method_card_type": "VISA",
  "create_date": "2025-06-24T12:49:35.571057+00:00",
  "update_date": "2025-06-24T12:51:02.118433+00:00"
}

Fields whose value is null are omitted from the response.

Response Fields

Field	Type	Description
status	string	processing, completed, failed or mispaid
transaction_id	UUID	Wirekassa transaction identifier
amount	string	Requested amount in major units
currency	string	ISO 4217 currency code
received_amount	string	Amount actually received; present when it differs from amount
redirect_url	string	Hosted checkout page for this transaction
channel	UUID	Merchant channel the transaction belongs to
external_id	string	Identifier you supplied when creating the payment
payment_method	string	Method type: card, sbp or cross_border
payment_method_<field>	string	Method details; the exact set depends on the method
create_date	string	ISO 8601 creation timestamp
update_date	string	ISO 8601 timestamp of the last status change
error_code	string	Present only when status is failed
error_message	string	Human-readable reason; present only when status is failed

Payment Method Details

The method type is returned in payment_method as a plain string.
Details of the method are flattened into payment_method_* keys, and the exact set depends on the type:

• card → payment_method_card_mask, payment_method_cardholder, payment_method_bank_name, payment_method_card_type, payment_method_user_agent, payment_method_user_ip. See Card
• sbp → payment_method_phone, payment_method_amount, payment_method_bank_name, payment_method_recipient, payment_method_qr. See SBP
• cross_border → payment_method_requisite_type, payment_method_number, payment_method_bank_name, payment_method_owner_name, payment_method_state. See Cross-Border

POST /v1/payment/

Creates a new payment transaction.

Request:

• Method: POST
• Headers: X-API-Key, X-Timestamp, X-Signature, Content-Type: application/json
• Body: flat JSON describing the transaction

Request Fields

Field	Type	Required	Description
channel	UUID	yes	Merchant channel identifier
amount	string	yes	Amount in major units, e.g. "1000.00"
currency	string	yes	ISO 4217 currency code
payment_method	string	yes	Method type, e.g. "card"
external_id	string	no	Your own order identifier; returned in responses and callbacks
return_url	string	no	Where the payer is sent after finishing on the hosted page
callback_url	string	no	Where status notifications are delivered
lang	string	no	Two-letter language code for the hosted page, e.g. "en"

Every other top-level key is treated as a field of the payment method.

Basic Example:

{
  "channel": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "1000.00",
  "currency": "RUB",
  "payment_method": "card",
  "external_id": "ORDER123",
  "return_url": "https://your-company.com/return"
}

Card Payment (extended):

{
  "channel": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "1000.00",
  "currency": "RUB",
  "payment_method": "card",
  "pan": "4111111111111111",
  "expiry_month": "03",
  "expiry_year": "2030",
  "cvc": "737",
  "cardholder": "S. Hopper",
  "external_id": "ORDER123",
  "return_url": "https://your-company.com/return"
}

Successful Response (201):

The create response has exactly the same shape as the GET response.

{
  "status": "processing",
  "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
  "amount": "1000.0",
  "currency": "RUB",
  "redirect_url": "https://pay.wirekassa.com/123e4567-e89b-12d3-a456-426614174000/",
  "channel": "550e8400-e29b-41d4-a716-446655440000",
  "external_id": "ORDER123",
  "payment_method": "card",
  "create_date": "2025-06-24T12:49:35.571057+00:00",
  "update_date": "2025-06-24T12:49:35.571057+00:00"
}

POST /v1/payment/confirm/

This endpoint exists for methods whose flow pauses to collect a reference from the payer. None of the methods on this account use it — card is completed through 3-D Secure, while SBP and Cross-Border are settled from the provider's report. You do not need to call it.

Error Handling

• 400 Bad Request → invalid or missing fields
• 401 Unauthorized → authentication failed

👉 Full list of error formats is available in the Error Responses section.

Additional Info

Mispaid status

If the payer transferred more or less money to the P2P order, the order goes to the status - MISPAID. In this case, you don't need to focus on the amount field, but on received_amount - it will store the paid amount for the payment.

Example Response

{
  "status": "mispaid",
  "transaction_id": "58d3f0a2-4c84-40d9-9ebe-e3b1137a49c8",
  "amount": "111.0",
  "currency": "RUB",
  "received_amount": "100.0",
  "redirect_url": "https://pay.wirekassa.com/58d3f0a2-4c84-40d9-9ebe-e3b1137a49c8/",
  "payment_method": "sbp",
  "create_date": "2025-10-15T11:19:17.254731+00:00"
}

Failed payments

When a payment is declined, the reason is returned in two flat fields:

{
  "status": "failed",
  "transaction_id": "58d3f0a2-4c84-40d9-9ebe-e3b1137a49c8",
  "amount": "111.0",
  "currency": "RUB",
  "payment_method": "sbp",
  "error_code": "PROVIDER_PROCESSING_FAILED",
  "error_message": "Payment provider returned an error.",
  "create_date": "2025-10-15T11:19:17.254731+00:00",
  "update_date": "2025-10-15T11:24:03.917882+00:00"
}