API Documentation

Appearance

Introduction ​

The Paylander Public Payment API enables secure server-to-server communication with systems such as online stores, billing platforms, and third-party services.
It provides endpoints to create and retrieve transactions.

All requests must be signed using an api_key and secret_key with HMAC-SHA256, ensuring authenticity and data integrity.
This guide is intended for developers integrating their backends with the API.

1. Workflow Overview ​

A standard integration flow consists of these steps:

Step 1. Authentication Headers ​

Every request must include:

  • X-API-Key → API key issued to the client
  • X-Timestamp → current Unix time in seconds
  • X-Signature → HMAC-SHA256 signature generated with the secret key

Signature rules:

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

⚠️ The timestamp must be within 5 minutes of the server time to prevent replay attacks.

Step 2. Constructing Requests ​

  • Base URL: https://api.paylander.com/
  • Methods supported:
    • GET → retrieve transaction data
    • POST → create new transaction
  • Request format:
    • For GET, add query parameters to the URL
    • For POST, include raw JSON in the request body
  • Headers: always include authentication headers; for POST, add Content-Type: application/json.

Step 3. Sending Requests ​

Example GET (curl) ​

bash
TIMESTAMP=$(date +%s)
QUERY="transaction_id=123"
MESSAGE="${TIMESTAMP}${QUERY}"
SIGNATURE=$(echo -n "$MESSAGE" | openssl dgst -sha256 -hmac "user1_secret_key" | awk '{print $2}')

curl -X GET "https://api.paylander.com/data/?${QUERY}"   -H "X-API-Key: user1_api_key"   -H "X-Signature: $SIGNATURE"   -H "X-Timestamp: $TIMESTAMP"

Example POST (curl) ​

bash
TIMESTAMP=$(date +%s)
PAYLOAD='{"amount": "100", "currency": "USD", "external_id": "ORDER123", "idempotency_key": "unique_key_123"}'
MESSAGE="${TIMESTAMP}${PAYLOAD}"
SIGNATURE=$(echo -n "$MESSAGE" | openssl dgst -sha256 -hmac "user1_secret_key" | awk '{print $2}')

curl -X POST "https://api.paylander.com/data/"   -H "X-API-Key: user1_api_key"   -H "X-Signature: $SIGNATURE"   -H "X-Timestamp: $TIMESTAMP"   -H "Content-Type: application/json"   -d "$PAYLOAD"

Step 4. Handling Responses ​

  • 200 OK → success; JSON payload with transaction details
  • 4xx → client-side issue (e.g. invalid parameters, malformed JSON)
  • 5xx → server-side error

Your backend should validate response codes, log failures, and retry when appropriate.

2. Data Exchange Pattern ​

The integration follows a simple request–response cycle:

  1. Client backend builds request with headers and payload
  2. Request is sent via HTTPS to the API
  3. API verifies authentication and processes data
  4. API returns JSON with status code

Security Requirements ​

  • HMAC signatures → required for every request
  • Timestamp checks → requests older than 5 minutes are rejected
  • HTTPS enforced → plain HTTP connections are not allowed

Known Limitations ​

  • Exact body signing: For POST requests, the JSON used in the signature must match the transmitted body exactly.
  • Key management: API keys are not automatically rotated. If a key is revoked or expired, new credentials must be issued via the dashboard.

© 2025 Paylander