Skip to main content
POST
/
api
/
payment
/
initiate
Initiate a new payment
curl --request POST \
  --url https://api.suby.fi/api/payment/initiate \
  --header 'Content-Type: application/json' \
  --header 'X-Suby-Api-Key: <api-key>' \
  --data '
{
  "productId": "pro_abc123xyz",
  "customerEmail": "customer@example.com",
  "successUrl": "https://your-app.com/success",
  "cancelUrl": "https://your-app.com/cancel",
  "externalRef": "order_789xyz",
  "metadata": {
    "orderId": "12345",
    "source": "mobile_app",
    "customField": "value"
  }
}
'
{
  "success": true,
  "data": {
    "paymentId": "pay_abc123xyz",
    "paymentUrl": "https://app.suby.fi/pay/pay_abc123xyz",
    "metadata": {}
  }
}

Authorizations

​
X-Suby-Api-Key
string
header
required

API key authentication. Include your API key in the X-Suby-Api-Key header:

X-Suby-Api-Key: your_api_key_here

Body

application/json
​
productId
string
required

Unique identifier of the subscription product the customer is purchasing

Example:

"pro_abc123xyz"

​
customerEmail
string<email>
required

Email address of the customer. If the customer doesn't exist, a new user account will be created automatically

Example:

"customer@example.com"

​
successUrl
string<uri>
required

URL to redirect the customer after successful payment completion (required)

Example:

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

​
cancelUrl
string<uri>
required

URL to redirect the customer if they cancel the payment (required)

Example:

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

​
externalRef
string

Your internal reference ID for tracking this payment in your system (e.g., order ID, invoice number)

Maximum string length: 255
Example:

"order_789xyz"

​
metadata
object

Custom key-value pairs to store with the payment. This data will be returned in webhooks

Example:
{
  "orderId": "12345",
  "source": "mobile_app",
  "customField": "value"
}

Response

Payment initiated successfully

​
success
boolean

Indicates if the request was successful

Example:

true

​
data
object