Payments API Reference
Introduction
The Payments API allows you to programmatically manage payment transactions, including creating, retrieving, listing, and canceling payments. It also provides endpoints for managing refunds and handling webhook notifications for asynchronous event processing.
This API is designed to be RESTful, using standard HTTP methods and JSON for request and response bodies.
Authentication
All requests to the Payments API must be authenticated. Authentication is performed using API keys, which should be included in the Authorization header of your requests.
Authorization: Bearer YOUR_API_KEY
Obtain your API key from your developer dashboard.
Payments
Create Payment
Initiates a new payment transaction.
Endpoint: POST /v1/payments
Request Body
{
"amount": 100.50,
"currency": "USD",
"description": "Monthly Subscription Fee",
"customer_id": "cust_12345",
"metadata": {
"order_id": "ORD-98765"
}
}
Parameters
-
amountnumber (required)
The amount to charge.
-
currencystring (required)
The currency of the amount (e.g., "USD", "EUR").
-
descriptionstring (optional)
A short description of the payment.
-
customer_idstring (optional)
The ID of the customer making the payment.
-
metadataobject (optional)
A key-value pair for additional information.
Response (Success)
{
"id": "pay_abc123",
"amount": 100.50,
"currency": "USD",
"status": "pending",
"created_at": "2023-10-27T10:00:00Z",
"customer_id": "cust_12345",
"description": "Monthly Subscription Fee",
"metadata": {
"order_id": "ORD-98765"
}
}
Response (Error)
{
"error": {
"code": "invalid_amount",
"message": "Amount must be a positive number."
}
}
Get Payment
Retrieves the details of a specific payment.
Endpoint: GET /v1/payments/{payment_id}
Path Parameters
-
payment_idstring (required)
The unique identifier of the payment.
Response (Success)
{
"id": "pay_abc123",
"amount": 100.50,
"currency": "USD",
"status": "succeeded",
"created_at": "2023-10-27T10:00:00Z",
"updated_at": "2023-10-27T10:05:00Z",
"customer_id": "cust_12345",
"description": "Monthly Subscription Fee",
"metadata": {
"order_id": "ORD-98765"
}
}
List Payments
Retrieves a list of payments, with options for filtering and pagination.
Endpoint: GET /v1/payments
Query Parameters
| Name | Type | Description |
|---|---|---|
| limit | integer | Maximum number of items to return. Default is 10. |
| offset | integer | Number of items to skip before returning results. Default is 0. |
| status | string | Filter by payment status (e.g., 'succeeded', 'failed', 'pending'). |
| customer_id | string | Filter by customer ID. |
Response (Success)
{
"data": [
{
"id": "pay_abc123",
"amount": 100.50,
"currency": "USD",
"status": "succeeded",
"created_at": "2023-10-27T10:00:00Z",
"customer_id": "cust_12345"
},
{
"id": "pay_def456",
"amount": 50.00,
"currency": "EUR",
"status": "pending",
"created_at": "2023-10-26T15:30:00Z",
"customer_id": "cust_67890"
}
],
"has_more": true,
"total_count": 50
}
Cancel Payment
Cancels a pending payment. This action is irreversible.
Endpoint: POST /v1/payments/{payment_id}/cancel
Path Parameters
-
payment_idstring (required)
The unique identifier of the payment to cancel.
Response (Success)
{
"id": "pay_abc123",
"amount": 100.50,
"currency": "USD",
"status": "canceled",
"created_at": "2023-10-27T10:00:00Z",
"customer_id": "cust_12345"
}
Refunds
Create Refund
Initiates a refund for a completed payment.
Endpoint: POST /v1/refunds
Request Body
{
"payment_id": "pay_abc123",
"amount": 50.25,
"reason": "Customer requested refund"
}
Parameters
-
payment_idstring (required)
The ID of the payment to refund.
-
amountnumber (optional)
The amount to refund. If not specified, the full payment amount will be refunded.
-
reasonstring (optional)
The reason for the refund.
Response (Success)
{
"id": "ref_xyz789",
"payment_id": "pay_abc123",
"amount": 50.25,
"currency": "USD",
"status": "processing",
"created_at": "2023-10-27T11:00:00Z",
"reason": "Customer requested refund"
}
Get Refund
Retrieves the details of a specific refund.
Endpoint: GET /v1/refunds/{refund_id}
Path Parameters
-
refund_idstring (required)
The unique identifier of the refund.
Response (Success)
{
"id": "ref_xyz789",
"payment_id": "pay_abc123",
"amount": 50.25,
"currency": "USD",
"status": "succeeded",
"created_at": "2023-10-27T11:00:00Z",
"updated_at": "2023-10-27T11:05:00Z",
"reason": "Customer requested refund"
}
List Refunds
Retrieves a list of refunds, with options for filtering and pagination.
Endpoint: GET /v1/refunds
Query Parameters
| Name | Type | Description |
|---|---|---|
| limit | integer | Maximum number of items to return. Default is 10. |
| offset | integer | Number of items to skip before returning results. Default is 0. |
| payment_id | string | Filter by payment ID. |
| status | string | Filter by refund status (e.g., 'succeeded', 'failed', 'processing'). |
Response (Success)
{
"data": [
{
"id": "ref_xyz789",
"payment_id": "pay_abc123",
"amount": 50.25,
"currency": "USD",
"status": "succeeded",
"created_at": "2023-10-27T11:00:00Z"
}
],
"has_more": false,
"total_count": 1
}
Webhooks
Webhooks allow your application to receive real-time notifications about events in your account, such as successful payments, failed payments, and refund statuses.
To set up webhooks:
- Go to your Developer Settings.
- Enter the URL where you want to receive webhook events.
- Select the events you wish to subscribe to.
We will send a POST request with a JSON payload to your specified URL for each subscribed event. Ensure your endpoint is publicly accessible and can handle incoming HTTP POST requests.
Example Event Payload (Payment Succeeded)
{
"event": "payment.succeeded",
"data": {
"id": "pay_abc123",
"amount": 100.50,
"currency": "USD",
"status": "succeeded",
"created_at": "2023-10-27T10:00:00Z",
"customer_id": "cust_12345"
},
"created_at": "2023-10-27T10:05:00Z"
}