API reference

The Plugipay API is a REST API that uses JSON for both requests and responses. It's the same API our portal and SDKs use; if you want to integrate Plugipay directly without an SDK, this section covers everything you need.

Base URL

https://api.plugipay.com

The same base URL handles both test and live API keys. The key itself determines the environment.

For staging:

https://api-staging.plugipay.com

You can get staging keys from us — email hello@plugipay.com.

Authentication

Every request must be signed. The Plugipay API uses HMAC-SHA256 request signing with an access key ID + secret pair.

Two headers per request:

Header	What it is
Authorization	Plugipay-HMAC-SHA256 keyId=<id>, scope=*, signature=<hex>
X-Plugipay-Timestamp	Current epoch seconds (must be within 300 seconds of server time)

Access key IDs are prefixed pk_test_* or pk_live_*; secrets are sk_test_* or sk_live_*.

The signing string is:

<METHOD>
<path>
<timestamp>
<sha256-hex(body)>
[<idempotency-key>]    (optional, if present)

See Authentication for the full signing recipe with worked examples.

The SDKs handle all this transparently. You only need to compute signatures manually with raw HTTP.

Response envelope

Every successful API response is wrapped in a uniform envelope:

{
  "data": { /* the response payload */ },
  "error": null,
  "meta": {
    "requestId": "req_01H...",
    "timestamp": "2026-05-12T10:42:00Z"
  }
}

List endpoints have a paginated variant:

{
  "data": [ /* items */ ],
  "error": null,
  "meta": {
    "requestId": "req_01H...",
    "timestamp": "2026-05-12T10:42:00Z",
    "page": {
      "limit": 50,
      "hasMore": true,
      "nextCursor": "cur_xxx"
    }
  }
}

Errors keep the envelope shape but set error:

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "amount must be a positive integer",
    "field": "amount"
  },
  "meta": { "requestId": "...", "timestamp": "..." }
}

See Conventions for the full envelope spec and Errors for the catalog of error codes.

Pagination

List endpoints use cursor-based pagination:

GET /v1/customers?limit=50

Response includes meta.page.nextCursor. To fetch the next page:

GET /v1/customers?limit=50&cursor=cur_xxx

When hasMore is false, you've reached the end.

See Pagination for cursors, ordering, and filtering options.

Idempotency

Mutating endpoints (POST, PUT, PATCH, DELETE) accept an Idempotency-Key header. If you send the same key twice within 24 hours, you get back the same response — no duplicate operation.

curl -X POST https://api.plugipay.com/v1/checkout-sessions \
  -H "Idempotency-Key: my-unique-attempt-id-001" \
  -H "Authorization: Plugipay-HMAC-SHA256 keyId=pk_test_xxx, scope=*, signature=..." \
  -H "X-Plugipay-Timestamp: ..." \
  ...

Use idempotency keys for any operation that creates money movement: payments, refunds, subscription cancellations. See Idempotency.

Rate limits

Default limits per workspace:

Endpoint class	Limit
Read (GET)	100 req/sec
Write (POST/PUT/PATCH/DELETE)	20 req/sec
Webhook delivery (to you)	No limit, but exponential backoff on failures

Limits are returned in response headers:

• X-RateLimit-Limit — the bucket size
• X-RateLimit-Remaining — how many requests left in the window
• X-RateLimit-Reset — epoch seconds when the bucket refills

On exceeding the limit you get 429 Too Many Requests with a Retry-After header.

See Rate limits for details and how to request increases.

Resources

The API is organized by resource. Each resource has a CRUD-like surface:

Resource	Path prefix
Customers	/v1/customers
Plans	/v1/plans
Checkout sessions	/v1/checkout-sessions
Payments	/v1/payments
Refunds	/v1/refunds
Subscriptions	/v1/subscriptions
Invoices	/v1/invoices
Portal sessions	/v1/portal-sessions
Webhook endpoints	/v1/webhook-endpoints
API keys	/v1/api-keys
Templates	/v1/templates
Adapters	/v1/adapters
Uploads	/v1/uploads
Workspaces	/v1/workspaces
Account	/v1/account

Each resource page documents every endpoint, every parameter, every response field.

Webhooks

Plugipay sends webhook events for state changes you care about: payment.succeeded, refund.failed, invoice.paid, and so on.

Events are signed; you verify the signature before trusting the payload. See Webhooks for the event catalog and the signature scheme.

OpenAPI spec

A machine-readable OpenAPI 3.0 spec is at api.plugipay.com/openapi.json. You can use it with any OpenAPI tooling (Postman, openapi-generator, etc.) to generate clients in languages we don't ship SDKs for.

Next

• Authentication — the full HMAC signing recipe with worked examples.
• Conventions — envelope, fields, types.
• Errors — the error catalog.
• Resources — every endpoint, every parameter.