API Documentation

Authentication

All merchant API requests require the X-Merchant-Key header with your API key. Obtain your key from the Admin dashboard after merchant creation.

X-Merchant-Key: liv_your_api_key_here

Create Payment

Unified entry: POST /v1/payments/create. Pix-specific: POST /v1/pix/create. Use Idempotency-Key for idempotent requests.

POST /v1/payments/create
Content-Type: application/json
X-Merchant-Key: liv_xxx
Idempotency-Key: unique-key-per-request  # Required for idempotency

{
  "amount": 100.00,
  "currency": "BRL",
  "recipientDocument": "12345678901",
  "recipientName": "John Doe",
  "description": "Optional description",
  "externalId": "your-order-id"
}

Success: 201 with { success, data, request_id, provider }.

Get Payment Status

GET /v1/payments/:id
GET /v1/pix/:id
X-Merchant-Key: liv_xxx

Webhooks

Configure webhook_url and optionally webhook_signing_secret for your merchant. We forward Z.ro events to your endpoint with:

• X-Webhook-Source: zro
• X-Webhook-Event: <event_type>
• X-Request-Id: <request_id>
• X-Webhook-Signature: HMAC-SHA256 (when signing secret is set)

# Simulate webhook (for testing)
curl -X POST https://api.luxinvest.tech/webhooks/zro \
  -H "Content-Type: application/json" \
  -d '{
    "event": "payment.confirmed",
    "id": "evt-123",
    "data": {"id": "pay-1", "amount": 100}
  }'

Error Codes

{
  "request_id": "uuid",
  "success": false,
  "provider": "zro",
  "error": {
    "code": "UPSTREAM_ERROR",
    "message": "Human readable error",
    "upstream_status": 400,
    "details": {}
  }
}