API Reference
The Paynectra API is organised around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
You can use the Paynectra API in test mode — which does not affect your live data or interact with real payment networks. The API key you use to authenticate the request determines whether the request is live or test.
/v1/payments
Create a Payment
Creates a new Payment object. A Payment represents the entire lifecycle of a payment transaction — from initial creation through authorisation, capture, and final settlement. Once created, you confirm it client-side using our JS SDK or redirect the customer to the hosted payment page.
Parameters
| Parameter | Type | Description |
|---|---|---|
| amount required | integer |
Amount in the smallest currency unit (e.g. cents for USD). A charge of $49.99 should be expressed
as 4999. |
| currency required | string |
Three-letter ISO currency code in lowercase. Must be a supported currency. |
| customer_id | string |
ID of an existing Customer. When provided, the payment is associated with that customer and enables saved card functionality. |
| description | string |
An arbitrary string attached to the object. Often useful for displaying to your merchant dashboard or customer receipt. |
| capture_method | string |
Controls when the funds will be captured. Defaults to automatic. Use
manual to place a hold and capture later.
|
| metadata | object |
Set of key-value pairs you can attach to the object. Useful for storing additional information such as your internal order ID. |
| return_url | string |
The URL to redirect your customer to after payment confirmation. Required for hosted checkout. |
/v1/payments/:id
Retrieve a Payment
Retrieves the details of a Payment that has previously been created. Supply the unique Payment ID that was returned from your previous request, and Paynectra will return the corresponding Payment information.
Parameters
| Parameter | Type | Description |
|---|---|---|
| id required | string |
The identifier of the Payment to be retrieved. Payment IDs are prefixed with pay_. |
/v1/payments
List all Payments
Returns a list of Payments. The payments are returned in reverse chronological order, with the most recently created appearing first. This endpoint supports cursor-based pagination.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | integer |
Number of objects to return. Defaults to 20, maximum 100. |
| starting_after | string |
Payment ID to use as cursor for forward pagination. |
| ending_before | string |
Payment ID to use as cursor for backward pagination. |
| customer | string |
Filter payments by customer ID. |
| status | string |
Filter by status: pending, succeeded, failed,
cancelled.
|
| created[gte] | timestamp |
Unix timestamp — return payments created on or after this date. |
| created[lte] | timestamp |
Unix timestamp — return payments created on or before this date. |
/v1/refunds
Create a Refund
Creates a Refund object. When you create a refund, Paynectra immediately submits the refund to the card network. Funds are typically returned to the customer within 5–10 business days, depending on the issuing bank. You can refund a payment in full or partially.
Parameters
| Parameter | Type | Description |
|---|---|---|
| payment_id required | string |
The ID of the Payment to refund. |
| amount | integer |
Amount to refund in smallest currency unit. Defaults to the full payment amount if omitted. |
| reason | string |
Reason for the refund: duplicate, fraudulent, or
customer_request.
|
| metadata | object |
Key-value pairs attached to the refund object. |
/v1/customers
Create a Customer
Creates a new Customer object. Use Customers to store payment methods, track subscription status, and manage ongoing billing relationships. Customers can have multiple saved payment methods.
Parameters
| Parameter | Type | Description |
|---|---|---|
string |
Customer's email address. Used for receipts and authentication flows. | |
| name | string |
The customer's full name or business name. |
| phone | string |
The customer's phone number in E.164 format. |
| address | object |
The customer's billing address — line1, city, postal_code,
country.
|
| metadata | object |
Key-value pairs for storing your internal customer data (e.g. your own user ID). |