Payout API

Overview

The Payout API allows backend systems to initiate and track payouts such as fund transfers to recipients.
It is designed for merchant platforms and financial services that require server-to-server communication.

All endpoints are REST-based and use HMAC-SHA256 signatures with an api_key and secret_key to guarantee secure access.

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

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

Authentication

Every request must include the following headers:

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

Signature rules:

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

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

Endpoints

GET /v1/payout/

Fetch details of an existing payout.

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/payout/?${QUERY}"   -H "X-API-Key: user1_api_key"   -H "X-Signature: $SIGNATURE"   -H "X-Timestamp: $TIMESTAMP"

Successful Response (200):

{
  "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "processing",
  "method": "card",
  "external_id": "ORDER123",
  "error_code": null,
  "error_message": null
}

• transaction_id → unique identifier for the payout
• status → current payout status (processing, completed, failed)
• method → the payout method type used
• external_id → identifier you supplied when creating the payout
• error_code / error_message → filled in only when status is failed, null otherwise

POST /v1/payout/

Create a new payout request.

Request:

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

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
payout_method	string	yes	Method type: "card"
external_id	string	no	Your own payout identifier; returned in responses and callbacks
callback_url	string	no	Where status notifications are delivered

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

Basic Example:

{
  "channel": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "1000.00",
  "currency": "RUB",
  "payout_method": "card",
  "pan": "4111111111111111",
  "external_id": "ORDER123"
}

Card Payout Example (extended):

{
  "channel": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "1000.00",
  "currency": "RUB",
  "payout_method": "card",
  "pan": "4111111111111111",
  "expiry_month": "01",
  "expiry_year": "3000",
  "holder_name": "S. Hopper",
  "external_id": "ORDER123",
  "callback_url": "https://your-company.com/callback"
}

Successful Response (200):

{
  "status": "processing",
  "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
  "external_id": "ORDER123",
  "error_code": null,
  "error_message": null
}

TIP

Payout creation answers with 200 OK, not 201.

Failed Payout Response (200):

{
  "status": "failed",
  "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
  "external_id": "ORDER123",
  "error_code": "DECLINED_GENERIC",
  "error_message": "The payout was declined."
}

---

Error Handling

• 400 Bad Request → invalid or missing parameters
• 401 Unauthorized → failed authentication
• 409 Conflict → insufficient balance on the channel

👉 See Error Responses for the full list of error codes and payload formats.