Payment links
Shareable links for one-time payments with no customer or stored card.
GET /v1/payment-links
List payment links
Cursor-paginated (limit, starting_after); filter by status.
- Authentication
- Merchant API key
- Effect
- Read-only.
Query parameters
| Name | Type | Required | Description |
|---|
limit | integer | no | Page size (1–100). · ≥ 1, ≤ 100, default 20 |
starting_after | string | no | Object ID; return objects after it (ascending ID order). · 26 chars |
status | "open" | "processing" | "completed" | "expired" | "canceled" | no | |
Responses
| Status | Meaning | Body / error codes |
|---|
| 200 | Success. | object |
| 400 | Invalid request. | invalid_query_param |
| 401 | Missing or invalid API key. | authentication_error |
| 429 | Rate limited; honor retry-after. | rate_limit_exceeded too_many_auth_failures |
| 500 | Server error. | api_error |
Example response
{
"object": "list",
"data": [
{
"object": "payment_link",
"id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"kind": "payment",
"status": "open",
"url": "https://example.com/hooks/payware",
"amount": 1,
"currency": "RON",
"description": "string",
"return_url": "https://example.com/hooks/payware",
"metadata": {},
"expires_at": "2026-10-25T18:00:00.000Z",
"payer_email": "string",
"payer_name": "string",
"payment_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"completed_at": "2026-10-25T18:00:00.000Z",
"created_at": "2026-10-25T18:00:00.000Z"
}
],
"has_more": false
}
POST /v1/payment-links
Create a payment link
Creates a link for a one-time payment with no customer and no stored card. Share url with the payer: a Payware page asks for their email, name and billing details, then sends them to NETOPIA Payments' secure page to pay. The link is single use, reopens if a payment attempt fails, and expires after expires_in_days (default 7). The result appears in GET /v1/payments as a payment with customer_id: null; read status there or consume payment.succeeded/payment.failed. An abandoned checkout stays pending until it is reconciled.
- Authentication
- Merchant API key
- Effect
- Creates a payment link; nothing is charged until the payer pays.
Headers
| Name | Type | Required | Description |
|---|
Idempotency-Key | string | no | Makes retries safe: same key + body replays the stored response (idempotency-replayed: true); a different body returns 409 idempotency_key_in_use. · ≤ 96 chars |
Request body
| Field | Type | Required | Description |
|---|
kind | "payment" | yes | |
amount | integer | yes | Minor units. · > 0, ≤ 2147483647 |
currency | "RON" | "EUR" | "USD" | yes | |
description | string | no | ≤ 500 chars |
return_url | string (uri) | no | Where the payer's browser goes after the hosted page, with payment_link_id appended. Must be a public http(s) URL. Arriving is not proof of payment. |
expires_in_days | integer | no | ≥ 1, ≤ 90, default 7 |
metadata | object | no | |
Example request
{
"kind": "payment",
"amount": 1,
"currency": "RON",
"description": "string",
"return_url": "https://example.com/hooks/payware",
"expires_in_days": 7,
"metadata": {}
}
Responses
| Status | Meaning | Body / error codes |
|---|
| 201 | Success. | PaymentLink |
| 400 | Invalid body, no usable instrument, or instrument not verified. | validation_failed instrument_required instrument_enrollment_required |
| 401 | Missing or invalid API key. | authentication_error |
| 429 | Rate limited; honor retry-after. | rate_limit_exceeded too_many_auth_failures |
| 500 | Server error. | api_error |
Example response
{
"object": "payment_link",
"id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"kind": "payment",
"status": "open",
"url": "https://example.com/hooks/payware",
"amount": 1,
"currency": "RON",
"description": "string",
"return_url": "https://example.com/hooks/payware",
"metadata": {},
"expires_at": "2026-10-25T18:00:00.000Z",
"payer_email": "string",
"payer_name": "string",
"payment_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"completed_at": "2026-10-25T18:00:00.000Z",
"created_at": "2026-10-25T18:00:00.000Z"
}
GET /v1/payment-links/:id
Retrieve a payment link
- Authentication
- Merchant API key
- Effect
- Read-only.
Path parameters
| Name | Type | Required | Description |
|---|
id | string | yes | Object ID (ULID). · 26 chars |
Responses
| Status | Meaning | Body / error codes |
|---|
| 200 | Success. | PaymentLink |
| 401 | Missing or invalid API key. | authentication_error |
| 404 | Not found, or not yours. | resource_missing |
| 429 | Rate limited; honor retry-after. | rate_limit_exceeded too_many_auth_failures |
| 500 | Server error. | api_error |
Example response
{
"object": "payment_link",
"id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"kind": "payment",
"status": "open",
"url": "https://example.com/hooks/payware",
"amount": 1,
"currency": "RON",
"description": "string",
"return_url": "https://example.com/hooks/payware",
"metadata": {},
"expires_at": "2026-10-25T18:00:00.000Z",
"payer_email": "string",
"payer_name": "string",
"payment_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"completed_at": "2026-10-25T18:00:00.000Z",
"created_at": "2026-10-25T18:00:00.000Z"
}
POST /v1/payment-links/:id/cancel
Cancel a payment link
Cancels an open link. A link with a payment in progress cannot be canceled (409).
- Authentication
- Merchant API key
- Effect
- Marks the link canceled.
Path parameters
| Name | Type | Required | Description |
|---|
id | string | yes | Object ID (ULID). · 26 chars |
Headers
| Name | Type | Required | Description |
|---|
Idempotency-Key | string | no | Makes retries safe: same key + body replays the stored response (idempotency-replayed: true); a different body returns 409 idempotency_key_in_use. · ≤ 96 chars |
Responses
| Status | Meaning | Body / error codes |
|---|
| 200 | Success. | PaymentLink |
| 401 | Missing or invalid API key. | authentication_error |
| 404 | Not found, or not yours. | resource_missing |
| 409 | Review is already resolved differently, or not open. | payment_review_already_resolved payment_review_not_open |
| 429 | Rate limited; honor retry-after. | rate_limit_exceeded too_many_auth_failures |
| 500 | Server error. | api_error |
Example response
{
"object": "payment_link",
"id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"kind": "payment",
"status": "open",
"url": "https://example.com/hooks/payware",
"amount": 1,
"currency": "RON",
"description": "string",
"return_url": "https://example.com/hooks/payware",
"metadata": {},
"expires_at": "2026-10-25T18:00:00.000Z",
"payer_email": "string",
"payer_name": "string",
"payment_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"completed_at": "2026-10-25T18:00:00.000Z",
"created_at": "2026-10-25T18:00:00.000Z"
}