Payments API

The Payments API allows you to create, retrieve, and manage payments across all your connected payment providers through a single unified interface.

Endpoints

POST/v1/payments

Create a new payment

GET/v1/payments/:id

Retrieve a payment by ID

GET/v1/payments

List all payments

The Payment Object

JSON

{
  "id": "pay_1234567890",
  "object": "payment",
  "amount": 2000,
  "currency": "usd",
  "status": "succeeded",
  "description": "Payment for Order #1234",
  "customer_id": "cus_abc123",
  "provider": "stripe",
  "provider_payment_id": "pi_xyz789",
  "metadata": {
    "order_id": "1234"
  },
  "created_at": "2026-01-19T10:30:00Z",
  "updated_at": "2026-01-19T10:30:05Z"
}

Attributes

Parameter	Type	Description
`id`	string	Unique identifier for the payment
`object`	string	Always "payment"
`amount`	integer	Amount in smallest currency unit (e.g., cents)
`currency`	string	Three-letter ISO currency code (e.g., "usd")
`status`	string	Payment status: pending, processing, succeeded, failed, canceled
`description`	string	Description of the payment
`customer_id`	string	ID of the associated customer (optional)
`provider`	string	Payment provider used (e.g., "stripe", "paypal")
`provider_payment_id`	string	ID from the payment provider
`metadata`	object	Custom key-value pairs for your use
`created_at`	string	ISO 8601 timestamp of creation
`updated_at`	string	ISO 8601 timestamp of last update

Create a Payment

POST/v1/payments

Create a new payment to charge a customer

Request Body

Parameter	Type	Description
`amount`required	integer	Amount in smallest currency unit (e.g., 2000 for $20.00)
`currency`required	string	Three-letter ISO currency code
`description`	string	Description for the payment
`customer_id`	string	ID of an existing customer
`provider`	string	Preferred payment provider. If not specified, uses smart routing
`metadata`	object	Custom key-value pairs

Example Request

cURL

curl https://api.vexutopia.com/v1/payments \
  -H "Authorization: Bearer vex_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2000,
    "currency": "usd",
    "description": "Payment for Order #1234",
    "metadata": {
      "order_id": "1234"
    }
  }'

JavaScript

const response = await fetch('https://api.vexutopia.com/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vex_test_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 2000,
    currency: 'usd',
    description: 'Payment for Order #1234',
    metadata: {
      order_id: '1234'
    }
  })
});

const payment = await response.json();
console.log(payment.id); // pay_1234567890

Response

JSON

{
  "id": "pay_1234567890",
  "object": "payment",
  "amount": 2000,
  "currency": "usd",
  "status": "succeeded",
  "description": "Payment for Order #1234",
  "customer_id": null,
  "provider": "stripe",
  "provider_payment_id": "pi_xyz789",
  "metadata": {
    "order_id": "1234"
  },
  "created_at": "2026-01-19T10:30:00Z",
  "updated_at": "2026-01-19T10:30:05Z"
}

Retrieve a Payment

GET/v1/payments/:id

Retrieve a payment by its unique identifier

Path Parameters

Parameter	Type	Description
`id`required	string	The payment ID (e.g., pay_1234567890)

Example Request

cURL

curl https://api.vexutopia.com/v1/payments/pay_1234567890 \
  -H "Authorization: Bearer vex_test_your_api_key"

JavaScript

const response = await fetch('https://api.vexutopia.com/v1/payments/pay_1234567890', {
  headers: {
    'Authorization': 'Bearer vex_test_your_api_key'
  }
});

const payment = await response.json();

List Payments

GET/v1/payments

List all payments with optional filtering

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results per page (default: 10, max: 100)
`offset`	integer	Number of results to skip (for pagination)
`status`	string	Filter by status: pending, processing, succeeded, failed, canceled
`customer_id`	string	Filter by customer ID
`created_after`	string	Filter payments created after this ISO 8601 timestamp
`created_before`	string	Filter payments created before this ISO 8601 timestamp

Example Request

cURL

curl "https://api.vexutopia.com/v1/payments?limit=10&status=succeeded" \
  -H "Authorization: Bearer vex_test_your_api_key"

JavaScript

const params = new URLSearchParams({
  limit: '10',
  status: 'succeeded'
});

const response = await fetch(`https://api.vexutopia.com/v1/payments?${params}`, {
  headers: {
    'Authorization': 'Bearer vex_test_your_api_key'
  }
});

const { data, total, has_more } = await response.json();

Response

JSON

{
  "object": "list",
  "data": [
    {
      "id": "pay_1234567890",
      "object": "payment",
      "amount": 2000,
      "currency": "usd",
      "status": "succeeded",
      ...
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0,
  "has_more": true
}

Error Handling

Common errors when working with the Payments API:

400Invalid Amount

Amount must be a positive integer

400Invalid Currency

Currency must be a valid 3-letter ISO code

404Payment Not Found

The specified payment ID does not exist

See the Errors reference for a complete list.

Next Steps

Learn more about related features:

Customers API Webhooks