API Documentation

Appearance

Card Payments ​

Use this page to create payments with bank cards using the common Payment API endpoint. Authentication and base URL follow the Payment API docs.

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

All request and response bodies are flat: amount and currency are separate top-level fields, payment_method is the method type as a string, and every card field sits at the top level of the body.

Integration Models ​

Card payments support two integration models:

  • Redirect flow: Only the method type is submitted. The customer is redirected to our secure hosted page to enter their card details.
  • Server-to-Server: You collect/handle card details; send full card data at the top level of the request body.

Redirect Flow ​

Use when card entry happens in our hosted frontend. Your backend only specifies the payment method type.

Common fields (see Payment API):

  • channel (UUID, required)
  • amount (string, required) → amount in major units
  • currency (ISO 4217, required)
  • external_id (string, optional)
  • return_url (string, recommended)
  • callback_url (string, optional)
  • payment_method (string, required) → "card"

Example Request (Hosted) ​

json
{
  "channel": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "100.00",
  "currency": "RUB",
  "payment_method": "card",
  "external_id": "ORDER-10002",
  "return_url": "https://your-company.com/return",
  "callback_url": "https://your-company.com/callback"
}

Example Response (Hosted) ​

json
{
  "status": "processing",
  "transaction_id": "269db9fa-440e-49a5-ab67-d30ecb75149e",
  "amount": "100.0",
  "currency": "RUB",
  "redirect_url": "https://pay.wirekassa.com/269db9fa-440e-49a5-ab67-d30ecb75149e/",
  "channel": "550e8400-e29b-41d4-a716-446655440000",
  "external_id": "ORDER-10002",
  "payment_method": "card",
  "create_date": "2025-10-15T23:54:13.008007+00:00",
  "update_date": "2025-10-15T23:54:13.008007+00:00"
}

Server-to-Server ​

Use when your backend handles card data directly. Ensure you comply with PCI-DSS requirements.

Card fields (payment_method: card) ​

Sent at the top level of the request body:

  • pan → Primary Account Number
  • expiry_month → "MM"
  • expiry_year → "YYYY"
  • cvc → Card security code
  • cardholder → Name on card

Any additional top-level key that is not an envelope field is collected as payer personal data and forwarded to the gateway. Commonly used ones:

  • email → Cardholder email
  • phone → Cardholder phone (E.164)
  • address → Full address string (if used instead of structured fields)
  • country_code → ISO 3166-1 alpha-2 country code (e.g., RU)
  • city → City name
  • street → Street line
  • postal_code → Postal/ZIP code
  • birth_date → Date of birth (e.g., YYYY-MM-DD)

Example Request (Server-to-Server) ​

json
{
  "channel": "328fffa1-4c63-44b4-9feb-76e8ad15176e",
  "amount": "1000.00",
  "currency": "RUB",
  "payment_method": "card",
  "pan": "400000000002",
  "expiry_month": "03",
  "expiry_year": "2030",
  "cvc": "737",
  "cardholder": "Ivan Petrov",
  "email": "ivan.petrov@example.ru",
  "phone": "79162171007",
  "address": "12 Tverskaya St, Moscow, Russia",
  "country_code": "RU",
  "city": "Moscow",
  "street": "Tverskaya St 12",
  "postal_code": "125009",
  "birth_date": "1990-05-14",
  "external_id": "ORDER-10001",
  "return_url": "https://your-company.com/return",
  "callback_url": "https://your-company.com/callback"
}

Example Response (Server-to-Server) ​

json
{
  "status": "processing",
  "transaction_id": "b4642e73-cbcb-4bb5-a0a4-98b2b76ebf59",
  "amount": "1000.0",
  "currency": "RUB",
  "redirect_url": "https://pay.wirekassa.com/b4642e73-cbcb-4bb5-a0a4-98b2b76ebf59/",
  "channel": "328fffa1-4c63-44b4-9feb-76e8ad15176e",
  "external_id": "ORDER-10001",
  "payment_method": "card",
  "payment_method_card_mask": "400000****0002",
  "payment_method_cardholder": "Ivan Petrov",
  "payment_method_bank_name": "Sberbank",
  "payment_method_card_type": "VISA",
  "create_date": "2025-10-15T23:53:44.803433+00:00",
  "update_date": "2025-10-15T23:53:44.803433+00:00"
}

Response fields (payment_method: card) ​

  • payment_method_card_mask → Masked card number
  • payment_method_cardholder → Name on card
  • payment_method_bank_name → Issuing bank
  • payment_method_card_type → Card network, e.g. VISA, MASTERCARD, MIR
  • payment_method_user_agent → Browser user agent captured during checkout
  • payment_method_user_ip → Payer IP address captured during checkout

Notes:

  • In both models, additional customer authentication (e.g., 3DS) may be required. When applicable, redirect the user using redirect_url.
  • Use the card number 400000000002 and the OTP 123456 to validate a successful transaction.

© 2025 Wirekassa