API Reference

Payment Links (Checkout)

A payment link is a hosted checkout page backed by a dedicated Stellar/USDC deposit address. Integrating one into your own checkout is server-to-server — create a link with your API key, get back a ready-to-use URL, and get notified when it's paid. No SDK or client-side signing required on your end.

Create a payment link

POST/v1/wallets/:id/payment-links

Field	Type	Description
namerequired	string	Shown to the payer on the checkout page.
description	string	Optional detail shown below the amount.
image_url	string	Optional image shown on the checkout page.
amount_usdc_stroops	integer	Fixed amount in USDC stroops (7dp). Omit for a flexible amount the payer enters themselves.
redirect_url	string	Where to send the payer's browser after a confirmed payment. See “Redirect back to your site” below.

Request

curl -X POST http://localhost:8080/v1/wallets/<WALLET_ID>/payment-links \
  -H "authorization: Bearer octo_sk_test_ab12…" \
  -H "content-type: application/json" \
  -d '{
    "name": "Pro plan — 1 month",
    "amount_usdc_stroops": 250000000,
    "redirect_url": "https://your-site.com/thank-you"
  }'

Response (201)

{
  "statusCode": 201,
  "message": "Created",
  "data": {
    "id": "b41a…",
    "slug": "ab12cd34ef",
    "name": "Pro plan — 1 month",
    "description": null,
    "image_url": null,
    "redirect_url": "https://your-site.com/thank-you",
    "amount_usdc_stroops": 250000000,
    "active": true,
    "collected_usdc_stroops": 0,
    "created_at": "2026-08-03T09:12:00Z",
    "url": "https://app.octo.dev/pay/ab12cd34ef"
  }
}

Share the checkout URL

data.url is the full hosted checkout page — link it, embed it, or put it in an iframe. Octo handles wallet connection, signing, and payment confirmation on that page; nothing else is required on your side.

The public checkout flow

The hosted page already implements the flow below — this is reference only, for understanding what happens behind the URL.

GET/v1/pay/:slug

POST/v1/pay/:slug/intent

GET/v1/pay/:slug/payments/:payment_id

POST/v1/pay/:slug/submit-signed

Get notified: the `payment_link.paid` webhook

POST to your URL

{
  "event": "payment_link.paid",
  "data": {
    "payment_link_id": "b41a…",
    "payment_id": "7c3e…",
    "slug": "ab12cd34ef",
    "payer_name": "Jane Doe",
    "payer_email": "jane@example.com",
    "amount_usdc_stroops": 250000000,
    "stellar_tx_hash": "9c0d…"
  }
}

Redirect back to your site

If you set redirect_urlwhen creating the link, the checkout page redirects the payer's browser there shortly after their payment is confirmed, with query params appended:

Redirect

https://your-site.com/thank-you?status=success&payment_id=7c3e…&slug=ab12cd34ef

⚠