App Endpoints

Blocks, files, email, and storage for installed apps.

Endpoints for installed apps. They require an app access token (pat_test_… / pat_live_…) from the POST /oauth/token exchange described in the Building apps guide — a merchant API key is refused with 403 and code app_required. Blocks and app data need no scope (the write is already bounded by the app’s own install); files needs files:write and emails needs emails:send.

These are the only endpoints in the reference with no Try it button. The playground signs requests with one of this workspace’s API keys, and no API key can call them — run them from your app with a token from the exchange instead.

Attach a block

Attach (or replace) a block on an object. Paysio renders it with its own components wherever that object is shown: a transaction block reaches the buyer (confirmation page, customer portal, receipt email) and the merchant (the transaction page in the dashboard); customer and subscription blocks reach the merchant on that record's page. Upserts on (app install, object, block type): re-posting the same type for the same object corrects the block instead of adding a second one, so retrying webhook handlers are safe.

POSThttps://paysio.com/api/v1/blocks

Authorizations

Authorizationstringheaderrequired

App access token (pat_) only. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Body

object_typestringrequired

"transaction", "customer" or "subscription"

object_idstringrequired

Must belong to the merchant workspace (404 otherwise)

typestringrequired

"details", "download", "status" or "link"

payloadobjectrequired

Block content. details/download: { title, description?, items: [{ label, value?, url?, copyable?, expires_at? }] }. status: { title, status, description?, items? }. link: { url, label, title?, description? }. Text is plain text; urls must be https or mailto

positioninteger

Sort order 0-999 (default 0)

Example request — cURL

curl -X POST https://paysio.com/api/v1/blocks \
  -H "Authorization: Bearer sk_test_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
  "object_type": "...",
  "object_id": "...",
  "type": "...",
  "payload": {}
}'

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/blocks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "object_type": "...",
    "object_id": "...",
    "type": "...",
    "payload": {}
  }),
})
const data = await res.json()

Example response (200)

{
  "object": "app_block",
  "id": "7a3d4e88-b2c1-4f6a-9d8e-1c9f4b1e0b0c",
  "object_type": "transaction",
  "object_id": "6b1e0d3a-9f7c-4d21-8a54-2c3b1e0f9a8d",
  "type": "download",
  "payload": { "title": "Your licence key", "items": [{ "label": "Key", "value": "XXXX-YYYY", "copyable": true }] },
  "position": 0,
  "created": 1735689600
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

List blocks

List this app's own blocks on one object. An app only ever sees the blocks it attached itself.

GEThttps://paysio.com/api/v1/blocks

Authorizations

Authorizationstringheaderrequired

App access token (pat_) only. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Query parameters

object_typestring

Required. "transaction", "customer" or "subscription"

object_idstring

Required. The object to inspect

Example request — cURL

curl -X GET https://paysio.com/api/v1/blocks \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/blocks", {
  method: "GET",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "data": [
    {
      "object": "app_block",
      "id": "7a3d4e88-b2c1-4f6a-9d8e-1c9f4b1e0b0c",
      "object_type": "transaction",
      "object_id": "6b1e0d3a-9f7c-4d21-8a54-2c3b1e0f9a8d",
      "type": "download",
      "payload": { "title": "Your licence key", "items": [{ "label": "Key", "value": "XXXX-YYYY", "copyable": true }] },
      "position": 0,
      "created": 1735689600
    }
  ],
  "has_more": false
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Remove a block

Remove one of this app's blocks. Scoped to the install, so an app can only ever delete its own.

DELETEhttps://paysio.com/api/v1/blocks/:id

Authorizations

Authorizationstringheaderrequired

App access token (pat_) only. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Example request — cURL

curl -X DELETE https://paysio.com/api/v1/blocks/:id \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/blocks/:id", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "id": "7a3d4e88-b2c1-4f6a-9d8e-1c9f4b1e0b0c",
  "object": "app_block",
  "deleted": true
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Upload a file

Upload a file (multipart form, field name 'file') to hand to a buyer — a licence key text file, a receipt PDF, a small image. Max 10 MB. Allowed types: application/pdf, image/png, image/jpeg, image/gif, image/webp, text/plain, text/csv, application/json, application/zip (no HTML or SVG — those could run script on the CDN origin). The returned id is the storage key and the url is public and immutable. There is no list endpoint — keep the returned ids in your own storage. Requires the files:write scope.

POSThttps://paysio.com/api/v1/files

Authorizations

Authorizationstringheaderrequired

App access token (pat_) only. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Body

filefilerequired

The file to upload (multipart form field)

Example request — cURL

curl -X POST https://paysio.com/api/v1/files \
  -H "Authorization: Bearer sk_test_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
  "file": "..."
}'

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/files", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "file": "..."
  }),
})
const data = await res.json()

Example response (200)

{
  "object": "file",
  "id": "app-files/<install-id>/live/9b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e.pdf",
  "url": "https://cdn.paysio.com/app-files/<install-id>/live/9b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e.pdf",
  "filename": "Manual.pdf",
  "content_type": "application/pdf",
  "size": 482133,
  "mode": "live"
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Delete a file

Delete an uploaded file. :id is the storage key returned at upload — it is path-shaped, so append it verbatim after /files/. 404 for any key outside this app's own prefix. Requires the files:write scope.

DELETEhttps://paysio.com/api/v1/files/:id

Authorizations

Authorizationstringheaderrequired

App access token (pat_) only. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Example request — cURL

curl -X DELETE https://paysio.com/api/v1/files/:id \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/files/:id", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "id": "app-files/<install-id>/live/9b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e.pdf",
  "object": "file",
  "deleted": true
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Send an email

Send an email to one of the merchant's customers, as the merchant. The sender address is resolved from the workspace (and its white-label brand) exactly as campaigns and invoices resolve it — it is never a parameter — and the recipient must already be a customer of the workspace, so an app can reach the merchant's customers and nobody else. Rate limited to 500 sends per app install per hour (429 beyond that). The body is plain text rendered into a branded shell; paragraphs split on blank lines. Test-mode sends succeed but are never delivered (delivered: false with a note). Requires the emails:send scope.

POSThttps://paysio.com/api/v1/emails

Authorizations

Authorizationstringheaderrequired

App access token (pat_) only. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Body

customer_idstring

The customer to email (preferred). One of customer_id / to is required

tostring

Alternative: a raw address, which must match an existing customer of the workspace (403 with code "recipient_not_allowed" otherwise)

subjectstringrequired

Max 200 chars

bodystringrequired

Plain text, max 100,000 chars

headingstring

Optional heading shown in the email (defaults to the subject)

Example request — cURL

curl -X POST https://paysio.com/api/v1/emails \
  -H "Authorization: Bearer sk_test_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "...",
  "body": "..."
}'

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/emails", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "subject": "...",
    "body": "..."
  }),
})
const data = await res.json()

Example response (200)

{
  "object": "email",
  "id": "0100019...",
  "to": "[email protected]",
  "subject": "Your licence key",
  "delivered": true,
  "mode": "live"
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

List stored keys

List this app's stored keys for the token's mode. Values are omitted — fetch a single key for its value. Storage is per install and per mode: a test token physically cannot read or write live rows, and rows are deleted 30 days after the app is uninstalled.

GEThttps://paysio.com/api/v1/app-data

Authorizations

Authorizationstringheaderrequired

App access token (pat_) only. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Example request — cURL

curl -X GET https://paysio.com/api/v1/app-data \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/app-data", {
  method: "GET",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "object": "list",
  "data": [
    { "object": "app_data", "key": "settings", "updated": 1735689600 }
  ]
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Retrieve a value

Retrieve one stored value. 404 when nothing is stored under the key.

GEThttps://paysio.com/api/v1/app-data/:key

Authorizations

Authorizationstringheaderrequired

App access token (pat_) only. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Example request — cURL

curl -X GET https://paysio.com/api/v1/app-data/:key \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/app-data/:key", {
  method: "GET",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "object": "app_data",
  "key": "settings",
  "value": { "theme": "dark", "notify": true },
  "updated": 1735689600
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Store a value

Create or replace the value stored under a key. Keys are 1-128 characters of letters, digits and ._:- only; values are any JSON up to 64KB; an install can hold at most 500 keys per mode (400 with code 'limit_exceeded' beyond that). This is a settings/state store for zero-backend apps, not a database.

PUThttps://paysio.com/api/v1/app-data/:key

Authorizations

Authorizationstringheaderrequired

App access token (pat_) only. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Body

valueany JSONrequired

The value to store, verbatim — returned as-is by GET

Example request — cURL

curl -X PUT https://paysio.com/api/v1/app-data/:key \
  -H "Authorization: Bearer sk_test_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
  "value": {}
}'

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/app-data/:key", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "value": {}
  }),
})
const data = await res.json()

Example response (200)

{
  "object": "app_data",
  "key": "settings",
  "value": { "theme": "dark", "notify": true },
  "updated": 1735689600
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Delete a key

Delete a stored key. Idempotent — deleting a missing key succeeds with deleted: false.

DELETEhttps://paysio.com/api/v1/app-data/:key

Authorizations

Authorizationstringheaderrequired

App access token (pat_) only. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Example request — cURL

curl -X DELETE https://paysio.com/api/v1/app-data/:key \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/app-data/:key", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "object": "app_data",
  "key": "settings",
  "deleted": true
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}