Payment API

Overview

The Payment API is a REST interface for backend integrations with the Paylander 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.paylander.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):

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.paylander.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": { 
    "currency": "EUR", 
    "value": "111.00" 
  },
  "redirect_url": "https://pay.paylander.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"
}

Failed Response (200, generic decline):

{
  "status": "failed",
  "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
  "amount": {
    "currency": "EUR",
    "value": "111.00"
  },
  "redirect_url": "https://pay.paylander.com/123e4567-e89b-12d3-a456-426614174000/",
  "channel": "8fec39b6-c41b-46d6-b219-61d115fdfa2d",
  "payment_method": {
    "type": "card",
    "card_mask": "4111********1111",
    "card_type": "VISA"
  },
  "create_date": "2025-06-24T12:49:35.571057+00:00",
  "error": {
    "code": "DECLINED_GENERIC",
    "message": "The payment was declined."
  }
}

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:

{
  "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):

{
  "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):

{
  "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.

Error Codes

The error object may be returned for failed transactions:

"error": {
  "code": "DECLINED_GENERIC",
  "message": "The payment was declined."
}

Possible Error Codes:

Code	Description
DECLINED_GENERIC	The payment was declined.
PERSONAL_DATA_NOT_PROVIDED	Personal data was not provided.
CARD_DATA_NOT_PROVIDED	Card data was not provided.
BROWSER_DATA_NOT_PROVIDED	Browser data was not provided.
DECLINED_3DS_AUTHENTICATION_FAILED	3-D Secure authentication failed.
PROVIDER_PROCESSING_FAILED	Payment provider returned an error (see details below).

Provider Error Details

For the PROVIDER_PROCESSING_FAILED code, the message field may contain various error descriptions returned directly by the payment provider.

Examples include (but are not limited to):

• Do not honor
• 3DS authentication error
• Insufficient funds
• Card expired
• Suspected fraud
• Transaction not permitted

These messages are passed through from the provider and may vary depending on the issuing bank or payment processor.

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

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