Payments

Create a payment request

Generate a new payment request for a product, subscription, or invoice.

The Create a Payment Request endpoint generates a payment request that can be sent to a customer. This is commonly used for invoicing, pre-authorizations, or collecting payments without immediately charging a card.

Endpoint

POST /v1/payments

Headers

Key	Value	Required
Content-Type	application/json	Yes
Authorization	Bearer <access_token>	Yes

Request Body

{
  "account_id": "acct_001",
  "amount": 7500,
  "currency": "USD",
  "customer_email": "customer@example.com",
  "reference": "invoice_12345",
  "metadata": {
    "order_id": "ord_456",
    "notes": "Payment due in 7 days"
  }
}

Field	Type	Required	Description
account_id	string	Yes	ID of the account requesting the payment.
amount	int	Yes	Payment amount in minor units (e.g., 7500 = $75.00).
currency	string	Yes	ISO 4217 currency code (e.g., USD, EUR).
customer_email	string	Yes	Email address of the customer to send the payment request.
reference	string	No	Optional external reference for tracking (e.g., invoice number).
metadata	object	No	Optional custom metadata for internal tracking.

Response

Successful Response (201 Created)

{
  "id": "pay_002",
  "account_id": "acct_001",
  "amount": 7500,
  "currency": "USD",
  "status": "pending",
  "customer_email": "customer@example.com",
  "reference": "invoice_12345",
  "metadata": {
    "order_id": "ord_456",
    "notes": "Payment due in 7 days"
  },
  "created_at": "2025-09-18T20:55:00Z",
  "payment_url": "https://pay.example.com/pay_002"
}

Field	Type	Description
id	string	Unique payment request ID.
account_id	string	ID of the account creating the request.
amount	int	Amount in minor units.
currency	string	Currency code.
status	string	Current status (pending, succeeded, failed).
customer_email	string	Email of the customer receiving the request.
reference	string	Optional external reference.
metadata	object	Custom metadata attached to the payment.
created_at	string	ISO 8601 timestamp of creation.
payment_url	string	Unique URL where the customer can complete the payment.

Error Response (400 / 402 / 404)

{
  "error": "invalid_request",
  "message": "Missing required fields or invalid currency."
}

Error Code	Meaning
invalid_request	Required fields missing or invalid.
unauthorized	Missing or invalid access token.
account_not_found	The provided account ID does not exist.

Example Usage

cURL

curl -X POST "https://api.example.com/v1/payments" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "account_id": "acct_001",
    "amount": 7500,
    "currency": "USD",
    "customer_email": "customer@example.com",
    "reference": "invoice_12345",
    "metadata": {
      "order_id": "ord_456",
      "notes": "Payment due in 7 days"
    }
  }'

JavaScript (Fetch)

const response = await fetch("https://api.example.com/v1/payments", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer your_access_token"
  },
  body: JSON.stringify({
    account_id: "acct_001",
    amount: 7500,
    currency: "USD",
    customer_email: "customer@example.com",
    reference: "invoice_12345",
    metadata: {
      order_id: "ord_456",
      notes: "Payment due in 7 days"
    }
  })
});

const data = await response.json();
console.log(data.payment_url); // URL for customer to pay

Payment requests remain in a pending status until the customer completes the payment. You can monitor status using the Check Payment Status endpoint.

Check payment status

Need help? Contact Support

Join our Discord Community

Questions? Contact Sales

On this page

Title