Introduction

​

Authentication

api-key: your_api_key_here

​

Base URLs

• Production: https://api.prod.payana.cloud/public/api/v1
• Develop: https://api.develop.payana.cloud/public/api/v1

​

Rate Limits

• 1000 requests per hour per API key
• 100 requests per minute (burst)

​

Webhooks

​

Webhook Headers

• Content-Type: application/json
• X-Payana-Signature: HMAC SHA256 del body
• X-Payana-Event: Tipo de evento (ej. payment.out.transaction.success)
• X-Payana-Timestamp: Timestamp ISO 8601

​

Signature Verification

const crypto = require('crypto');

function verifyWebhookSignature(body, signature, secretKey) {
  const expectedSignature = crypto
    .createHmac('sha256', secretKey)
    .update(JSON.stringify(body))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

​

Error Responses

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid data",
    "details": {
      "amount_cents": ["Amount must be greater than 0"],
      "beneficiary_id": ["Beneficiary does not exist"]
    }
  }
}

​

Common Error Codes

• VALIDATION_ERROR (400)
• UNAUTHORIZED (401)
• FORBIDDEN (403)
• NOT_FOUND (404)
• CONFLICT (409)
• RATE_LIMITED (429)
• INTERNAL_ERROR (500)

​

Status Codes

​

Payable Status Values

• pending
• scheduled
• processing
• paid
• failed
• refunded