Gyvar docs
API reference v1Lightning

Pay over Lightning

Pays a bolt11 invoice or a Lightning address. Send one of `invoice` or `lightning_address`. `amount_sat` is required with a Lightning address, and refused with an invoice, which carries its own amount.

POST
/lightning/pay

Authorization

KeyID Timestamp Nonce Signature
X-Gyvar-Key<token>

Your key id, gyv_k_live_... or gyv_k_sandbox_....

In: header

X-Gyvar-Timestamp<token>

Unix seconds. Must be within 5 minutes of our clock.

In: header

X-Gyvar-Nonce<token>

A unique value per request. Replays are rejected.

In: header

X-Gyvar-Signature<token>

Ed25519 signature over the canonical string. See the Signing guide.

In: header

Header Parameters

Idempotency-Key*string

Unique per payment. Retrying with the same key returns the same order.

Lengthlength <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

invoice?string

A bolt11. Mutually exclusive with lightning_address.

lightning_address?string
amount_sat?integer

Required with lightning_address, refused with invoice.

memo?string
customer_id?string

Optional. The customer this payment is for.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/lightning/pay" \  -H "Idempotency-Key: 9f1c2f7e-3a55-4a1f-9d3f-6f6a0f4e51b2" \  -H "Content-Type: application/json" \  -d '{    "invoice": "lnbc250u1p4fsmyc..."  }'
{  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "reference": "string",    "status": "successful",    "currency": "string",    "amount": "string",    "amount_minor": "string",    "fee": "string",    "fee_minor": "string",    "created_at": "2019-08-24T14:15:22Z"  }}

Create an invoice

Creates an invoice for a fixed amount. Every call creates a new one, so a retried request gives you a second invoice - only one can be paid, and unpaid invoices expire. Needs the `receive` capability.

Payouts

Pay out in local currency to mobile money and bank accounts, from a Bitcoin or stablecoin balance.