Payout API

Overview

The Payout API allows backend systems to initiate and track payouts such as fund transfers to recipients.
It is designed for merchant platforms and financial services that require server-to-server communication.

All endpoints are REST-based and use HMAC-SHA256 signatures with an api_key and secret_key to guarantee secure access.

• Base URL: https://api.paylander.com/

Authentication

Every request must include the following headers:

• X-API-Key → client’s API key
• X-Timestamp → current Unix time (seconds)
• X-Signature → HMAC-SHA256 signature created with the secret key

Signature rules:

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

⚠️ Requests older than 5 minutes relative to server time will be rejected.

Endpoints

GET /api/v1/payout/

Fetch details of an existing payout.

Request:

• Method: GET
• Required query parameters:
  • channel (UUID)
  • transaction_id (UUID, optional)
  • external_id (string, optional)

👉 At least one of 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/payout/?${QUERY}"   -H "X-API-Key: user1_api_key"   -H "X-Signature: $SIGNATURE"   -H "X-Timestamp: $TIMESTAMP"

Successful Response (200):

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

Failed Response (200, generic decline):

{
  "status": "failed",
  "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
  "method": "rocket",
  "external_id": "ORDER123",
  "error": {
    "code": "DECLINED_GENERIC",
    "message": "The payout was declined."
  }
}

• status → current payout status (pending, completed, failed)
• transaction_id → unique identifier for the payout
• error → decline details for failed payouts

POST /api/v1/payout/

Create a new payout request.

Request:

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

Basic Example:

{
  "channel": "550e8400-e29b-41d4-a716-446655440000",
  "amount": { 
    "currency": "USD", 
    "value": "1000.00" 
  },
  "external_id": "ORDER123",
  "payout_method": { "type": "scheme" }
}

Card Payout Example (extended):

{
  "channel": "550e8400-e29b-41d4-a716-446655440000",
  "amount": { 
    "currency": "USD", 
    "value": "1000.00" 
  },
  "external_id": "ORDER123",
  "payout_method": {
    "type": "card",
    "pan": "4111111111111111"
  }
}

• channel (UUID) → merchant channel identifier
• amount (object) → payout amount (currency + value)
• external_id (string) → unique identifier from the client system (e.g. order number)
• payout_method (object) → method of payout, type may be card, scheme, or others

Successful Response (201):

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

---

Error Handling

• 400 Bad Request → invalid or missing parameters
• 401 Unauthorized → failed authentication

👉 See Error Responses for the full list of error codes and payload formats.