API Documentation

Appearance

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/

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 5 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)

👉 Either transaction_id or external_id must be included.

Example (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"

Successful Response (200):

json
{
  "status": "processing",
  "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
  "amount": { 
    "currency": "EUR", 
    "value": "111.00" 
  },
  "redirect_url": "https://pay.wirekassa.com/123e4567-e89b-12d3-a456-426614174000/",
  "channel": "8fec39b6-c41b-46d6-b219-61d115fdfa2d",
  "payment_method": {
    "type": "card",
    "card_mask": "4111********1111",
    "cardholder": "S. Hopper",
    "user_agent": "Mozilla/5.0 ...",
    "user_ip": "203.0.113.42",
    "bank_name": "Example Bank",
    "card_type": "VISA"
  },
  "create_date": "2025-06-24T12:49:35.571057+00:00"
}

Payment Method Object ​

The payment_method object describes the method used to pay.
Its fields depend on the type:

  • card → details about bank cards (mask, bank, type, etc.)
  • havale → bank transfer (phone, user_id, names)
  • other → flexible structure for custom methods

POST /v1/payment/ ​

Creates a new payment transaction.

Request:

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

Basic Example:

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

Card Payment (extended):

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

Successful Response (201):

json
{
  "status": "pending",
  "transaction_id": "123e4567-e89b-12d3-a456-426614174000"
}

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 value in the amount field, but on received - it will store the paid amount for the payment.

Example Response ​

json
{
  "status": "mispaid",
  "transaction_id": "58d3f0a2-4c84-40d9-9ebe-e3b1137a49c8",
  "amount": {
    "currency": "INR",
    "value": "111.00",
    "received": "100.00"
  },
  "redirect_url": "https://pay.wirekassa.com/upi/58d3f0a2-4c84-40d9-9ebe-e3b1137a49c8/",
  "create_date": "2025-10-15T11:19:17.254731+00:00"
}

© 2025 Wirekassa