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.paylander.com/api/v1/payment/
  • Endpoint: POST /v1/payment/

Supported Currencies ​

  • EUR

Integration Models ​

Card payments support two integration models:

  • Redirect flow: Only the type parameter 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 in payment_method.

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 (object, required)
    • currency (ISO 4217, required)
    • value (string, required)
  • external_id (string, optional)
  • return_url (string, recommended)
  • payment_method (object, required)

payment_method (type: card) ​

Required:

  • type → "card"

Example Request (Hosted) ​

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

Example Response (Hosted) ​

Click to expand
json
{
  "status": "processing",
  "transaction_id": "269db9fa-440e-49a5-ab67-d30ecb75149e",
  "amount": {
    "currency": "EUR",
    "value": "100.00"
  },
  "redirect_url": "https://pay.paylander.com/269db9fa-440e-49a5-ab67-d30ecb75149e/",
  "channel": "550e8400-e29b-41d4-a716-446655440000",
  "payment_method": {
    "type": "card"
  },
  "create_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.

Common fields (see Payment API):

  • channel (UUID, required)
  • amount (object, required)
    • currency (ISO 4217, required)
    • value (string, required)
  • external_id (string, optional)
  • return_url (string, recommended)
  • payment_method (object, required)

payment_method (type: card) ​

Supported fields for Server-to-Server:

  • type → "card"
  • pan → Primary Account Number
  • expiry_month → "MM"
  • expiry_year → "YYYY"
  • cvc → Card security code
  • cardholder → Name on card
  • 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., KZ)
  • 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": { 
    "currency": "EUR", 
    "value": "1000.00" 
  },
  "external_id": "ORDER-10001",
  "payment_method": {
    "type": "card",
    "pan": "400000000002",
    "expiry_month": "03",
    "expiry_year": "2030",
    "cvc": "737",
    "cardholder": "Aruzhan Beketova",
    "email": "aruzhan.beketova@example.kz",
    "phone": "77011234567",
    "address": "52 Abay Ave, Almaty, Kazakhstan",
    "country_code": "KZ",
    "city": "Almaty",
    "street": "Abay Ave 52",
    "postal_code": "050000",
    "birth_date": "1990-05-14"
  },
  "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": {
    "currency": "KZT",
    "value": "1000.00"
  },
  "redirect_url": "https://pay.paylander.com/b4642e73-cbcb-4bb5-a0a4-98b2b76ebf59/",
  "channel": "328fffa1-4c63-44b4-9feb-76e8ad15176e",
  "payment_method": {
    "type": "card",
    "card_mask": "4000****0002",
    "cardholder": "Aruzhan Beketova",
    "bank_name": "Halyk Bank",
    "card_type": "VISA"
  },
  "create_date": "2025-10-15T23:53:44.803433+00:00"
}

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 Paylander