SigilPay Developer API

The SigilPay API is organized around REST and lives under a versioned base path. All requests and responses use JSON.

Base URL: https://api.sigilpay.com/v1  (this deployment: /api/v1)

Sandbox-mode keys (sk_test_...) never move real money — every provider call is simulated.

Authentication

Authenticate by including your API key in the Authorization header as a Bearer token. Create keys from your Business dashboard → Developers.

curl https://yourapp.example.com/api/v1/payments \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxx"

Payments

POST /api/v1/payments — create and process a payment. Amount, currency, and method are required.

curl -X POST https://yourapp.example.com/api/v1/payments \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5c1e9c3a-2b1e-4a3a-9c3a-2b1e4a3a9c3a" \
  -d '{"amount": 49.99, "currency": "USD", "method": "card", "description": "Order #1042"}'

{
  "payment": {
    "id": "pay_lz3k...",
    "object": "payment",
    "status": "successful",
    "amount": 49.99,
    "currency": "USD",
    "provider_transaction_id": "meridian_pay_ab12cd34ef56"
  }
}

GET /api/v1/payments and GET /api/v1/payments/:id retrieve payments belonging to your organization.

Possible status values: created, pending, processing, successful, failed, cancelled, expired, refunded, reversed. Status is only ever set from a verified provider response or verified webhook — never from client input.

Refunds

POST /api/v1/refunds — refund a successful payment, in full or in part.

curl -X POST https://yourapp.example.com/api/v1/refunds \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"paymentId": "pay_lz3k...", "amount": 20.00, "reason": "Customer request"}'

Transfers

POST /api/v1/transfers — send funds to a beneficiary via SigilPay's approved transfer partners.

curl -X POST https://yourapp.example.com/api/v1/transfers \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"beneficiaryId": "ben_...", "amount": 500, "currency": "USD", "purpose": "Vendor payout"}'

Insufficient balance returns 402 with error: "insufficient_funds". Funds are reserved before the provider call and automatically released if the provider rejects the transfer.

Customers

POST /api/v1/customers and GET /api/v1/customers manage your organization's customer records.

Invoices

POST /api/v1/invoices and GET /api/v1/invoices/:id create and retrieve invoices.

Webhooks

Configure a webhook endpoint from your dashboard to receive event notifications. Every delivery includes an X-SigilPay-Signature header — an HMAC-SHA256 signature of the raw request body, signed with your webhook secret.

const crypto = require('crypto');
function verify(rawBody, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Always verify the signature before trusting a webhook payload. Never process an unverified webhook.

Idempotency

Pass an Idempotency-Key header on payment/transfer creation requests. Retrying the same key with the same payload returns the original result — no duplicate money movement. Reusing a key with a different payload returns 409 idempotency_conflict.

Sandbox & Simulation

Sandbox-mode API keys let you simulate outcomes without real money movement by passing a simulate field: "success", "failure", or "pending".

-d '{"amount": 10, "currency": "USD", "method": "card", "simulate": "failure"}'

For a pending payment or transfer, use the in-app Sandbox tools (or your own call to the provider webhook receiver) to simulate the provider's eventual confirmation.

Errors

Errors use conventional HTTP status codes and a consistent JSON body: {"error": "bad_request", "message": "..."}.

• 400 bad_request — invalid or missing parameters
• 401 unauthorized — missing/invalid API key or session
• 402 insufficient_funds — wallet balance too low for a transfer
• 403 forbidden — authenticated but not authorized for this resource
• 404 not_found
• 409 idempotency_conflict — same key, different payload
• 503 no_provider_available — no active partner supports this request's country/currency/service combination