Skip to main content
POST
/
api
/
payment
/
create
Create a one-time payment
curl --request POST \
  --url https://api.suby.fi/api/payment/create \
  --header 'Content-Type: application/json' \
  --header 'X-Suby-Api-Key: <api-key>' \
  --data '
{
  "productId": "pro_abc123",
  "customerEmail": "customer@example.com",
  "customerFirstName": "John",
  "customerLastName": "Doe",
  "priceCents": "2500",
  "currency": "USD",
  "externalRef": "order_789",
  "metadata": {},
  "customFields": [
    {
      "key": "discord_username",
      "label": "Discord username",
      "required": false,
      "placeholder": "e.g. test#1234",
      "options": [
        {
          "value": "twitter",
          "label": "Twitter / X"
        }
      ],
      "validation": {
        "regex": "^.{2,32}$",
        "errorMessage": "Please enter a valid Discord username"
      }
    }
  ],
  "successUrl": "https://your-app.com/success",
  "cancelUrl": "https://your-app.com/cancel"
}
'
{
  "success": true,
  "data": {
    "paymentId": "pay_abc123",
    "paymentUrl": "https://checkout.suby.fi/pay/pay_abc123",
    "metadata": {},
    "customFields": [
      {
        "key": "discord_username",
        "label": "Discord username",
        "required": false,
        "placeholder": "e.g. test#1234",
        "options": [
          {
            "value": "twitter",
            "label": "Twitter / X"
          }
        ],
        "validation": {
          "regex": "^.{2,32}$",
          "errorMessage": "Please enter a valid Discord username"
        }
      }
    ]
  }
}

Documentation Index

Fetch the complete documentation index at: https://documentation.suby.fi/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
X-Suby-Api-Key
string
header
required

API key authentication

Body

application/json
​
productId
string
required

ID of a one-time product

Example:

"pro_abc123"

​
customerEmail
string<email>

Optional. If provided, a user account is created (or reused) immediately and linked to the payment. If omitted, the payment is created without a customer. The email will be collected on the hosted checkout page and the user will be linked to the payment at that moment.

Example:

"customer@example.com"

​
customerFirstName
string

Optional. Customer first name. Used to prefill checkout fields. Ignored when customerEmail is omitted.

Maximum string length: 100
Example:

"John"

​
customerLastName
string

Optional. Customer last name. Used to prefill checkout fields. Ignored when customerEmail is omitted.

Maximum string length: 100
Example:

"Doe"

​
priceCents
string

Price in cents as a string. Required when the product has isCustomPrice: true. Must NOT be provided for fixed-price products.

Example:

"2500"

​
currency
enum<string>

Currency for the price. Required when priceCents is provided, ignored otherwise.

Available options:
USD,
EUR
Example:

"USD"

​
externalRef
string

Your internal reference (order ID, invoice number, etc.)

Maximum string length: 255
Example:

"order_789"

​
metadata
object

Custom key-value pairs. Returned in webhooks.

​
customFields
object[]

Extra fields shown on the checkout page to collect information from the customer (e.g. Discord username, referral source, terms acceptance). Customer responses are returned in the context.customFieldsResponse object of every payment webhook.

Maximum 10 fields per payment. For subscriptions, fields are collected on the initial checkout only — renewals do not re-prompt the customer, and their webhooks will have customFields and customFieldsResponse set to null.

Maximum array length: 10
​
successUrl
string<uri>

Redirect URL after successful payment

Example:

"https://your-app.com/success"

​
cancelUrl
string<uri>

Redirect URL if customer cancels

Example:

"https://your-app.com/cancel"

Response

Payment created

​
success
boolean
Example:

true

​
data
object