Enrollments
Hosted 0 RON enrollment that produces a verified instrument.
POST /v1/enrollments
Start a hosted enrollment
Starts a 0 RON enrollment on NETOPIA Payments' hosted page. Poll GET /v1/enrollments/{id}; once requires_action, redirect the customer to checkout_url. Browser return parameters are not proof of success — wait for succeeded and a non-null instrument_id.
- Authentication
- Merchant API key
- Effect
- Durably queues a 0 RON enrollment (submitted after commit); emits
enrollment.created.
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 |
|---|---|---|---|
customer_id | string | yes | ULID · 26 chars |
return_url | string (uri) | no | Optional. After hosted checkout the customer returns through Payware and is redirected here with enrollment_id appended. The return is not proof of success; wait for the enrollment.updated/instrument.attached webhooks or poll the enrollment. Same URL rules as webhooks. · ≤ 2048 chars |
Example request
{
"customer_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"return_url": "https://example.com/hooks/payware"
}Responses
| Status | Meaning | Body / error codes |
|---|---|---|
| 202 | Accepted; status: pending, checkout_url: null. | Enrollment |
| 400 | Invalid body or return_url. | validation_failed invalid_json invalid_return_url |
| 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": "enrollment",
"id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"merchant_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"customer_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"status": "pending",
"amount": 0,
"currency": "RON",
"netopia_ntp_id": "string",
"instrument_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"error_message": "string",
"checkout_url": "string",
"created_at": "2026-10-25T18:00:00.000Z",
"updated_at": "2026-10-25T18:00:00.000Z",
"return_url": "https://example.com/hooks/payware"
}GET /v1/enrollments/:id
Retrieve an enrollment
Returns checkout_url once available. Treat it as sensitive.
- 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. | Enrollment |
| 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": "enrollment",
"id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"merchant_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"customer_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"status": "pending",
"amount": 0,
"currency": "RON",
"netopia_ntp_id": "string",
"instrument_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"error_message": "string",
"checkout_url": "string",
"created_at": "2026-10-25T18:00:00.000Z",
"updated_at": "2026-10-25T18:00:00.000Z",
"return_url": "https://example.com/hooks/payware"
}