Reference

API reference

Every endpoint, from the live OpenAPI spec.

Reading the live spec

v1 (snapshot)

Base URL: https://pay.perly.io/api/v1

Authenticate with your secret key as a bearer token.

bash

Authorization: Bearer sk_test_…

Invoices

GET/invoices

List invoices

Parameters

status (query): string
limit (query): integer1–100, default 20.
after (query): stringCursor from the last page.

Responses

200A page of invoices.

bash

curl https://pay.perly.io/api/v1/invoices \
  -H "Authorization: Bearer sk_test_…"

POST/invoices

Create an invoice

Body

line_items: object[]Prices ({ price, quantity }) or your own lines ({ description, amount, quantity }).
amount: integerOne amount instead of line_items, in minor units: 2400 is $24.00.
description: stringWith amount: what it is for.
currency: "USD" | "EUR"
customer: stringA customer id, or { email } to find or make one.
return_url: stringWhere the buyer's page sends them back.
metadata: objectUp to 20 keys, sent back in webhooks.

Responses

201The invoice, with its checkout url.
422A field is wrong.

bash

curl -X POST https://pay.perly.io/api/v1/invoices \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{}'

GET/invoices/{id}

Get an invoice

Parameters

idrequired: string

Responses

200The invoice.
404No such invoice in this mode.

bash

curl https://pay.perly.io/api/v1/invoices/{id} \
  -H "Authorization: Bearer sk_test_…"

POST/invoices/{id}/cancel

Cancel an open invoice

Parameters

idrequired: string

Responses

200Canceled.
409Money already arrived.

bash

curl -X POST https://pay.perly.io/api/v1/invoices/{id}/cancel \
  -H "Authorization: Bearer sk_test_…"

Test mode

POST/invoices/{id}/simulate

Simulate a payment (test mode only)

Parameters

idrequired: string

Body

outcome: "full" | "short" | "over"

Responses

200The invoice after the simulated transfer.
403Live keys can't simulate.

bash

curl -X POST https://pay.perly.io/api/v1/invoices/{id}/simulate \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{}'

Refunds

POST/refunds

Open a refund

Body

invoicerequired: string
amount: stringLeave out for all of it.

Responses

201The refund; the buyer is emailed a link for their address.
400sanctioned_sender: money on the invoice came from an address on a sanctions list, or one its issuer froze. It is never refunded.

bash

curl -X POST https://pay.perly.io/api/v1/refunds \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"invoice": …}'

Customers

GET/customers

List customers

Responses

200A page of customers.

bash

curl https://pay.perly.io/api/v1/customers \
  -H "Authorization: Bearer sk_test_…"

Subscriptions

GET/subscriptions/{id}

Get a subscription

Parameters

idrequired: string

Responses

200The subscription and its current period.

bash

curl https://pay.perly.io/api/v1/subscriptions/{id} \
  -H "Authorization: Bearer sk_test_…"

Webhooks

POST/webhook_endpoints

Add a webhook endpoint

Body

urlrequired: string
events: string[]

Responses

201The endpoint, with its whsec_… secret shown once.

bash

curl -X POST https://pay.perly.io/api/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"url": …}'