External Orders Endpoints

Server

Endpoints for creating and tracking partner (external) payment orders.

Get External Orders

GET

https://sandbox-api.vignette.id

/public/external-orders

Returns a paginated, filterable list of external orders for the authenticated partner.

⚠️ Rate limit policy applies to this endpoint Check Rate Limits

Get External Orders › query Parameters

status

string

Filter by one or more statuses. Comma-separated. Allowed values: CREATED, COMPLETED, FAILED, REFUNDED. Example: COMPLETED,CREATED.

currency

string

Filter by currency code, e.g. EUR.

payment_provider

string

Filter by the payment provider that processed the order, e.g. stripe, monobank.

subaccount

string

Filter by partner sub-account name.

created_after

string

Return orders created at or after this moment. Accepts an ISO 8601 date (2026-07-01) or a UNIX timestamp.

created_before

string

Return orders created at or before this moment. Accepts an ISO 8601 date (2026-07-01) or a UNIX timestamp.

amount_min

number

Return orders with amount greater than or equal to this value (major units).

amount_max

number

Return orders with amount less than or equal to this value (major units).

sort_by

string

Field to sort by. Supported: created_at, paid_at, completed_at, amount. Default created_at.

Default: created_at

order

string · enum

Sort direction. asc or desc. Default desc.

Enum values:

asc

desc

Default: desc

page

number

Page number for pagination. Default 1.

Default: 1

limit

number

Number of items per page. Default 25.

Default: 25

bug_report

boolean

Use with all endpoints to inform us for bugs in API

Default: false

Get External Orders › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get External Orders › Responses

List of external orders

ExternalOrdersListObject

error

object | null

object

total

integer

Total number of orders matching the filter.

limit

integer

ExternalOrderResult[]

GET/public/external-orders

curl https://sandbox-api.vignette.id/public/external-orders \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "error": null,
  "pages": {
    "total": 1,
    "current": 1
  },
  "total": 9,
  "limit": 25,
  "result": [
    {
      "id": "eo_UwMWPQcOF1LhlmMU",
      "reference_id": "esim-8",
      "status": "FAILED",
      "product": "esim",
      "description": "Esim",
      "amount": 25.99,
      "currency": "EUR",
      "email": "customer@example.com",
      "subaccount": "web-shop",
      "payment_provider": null,
      "allowed_payment_providers": [
        "stripe"
      ],
      "callback_url": "https://vignette.id/api/track/events/webhook",
      "success_url": null,
      "cancel_url": null,
      "open_order_details_by_default": false,
      "is_sandbox": true,
      "error_message": "No payment provider checkout could be created",
      "created_at": "2026-07-27T10:33:31.971+00:00",
      "paid_at": null,
      "completed_at": null,
      "payment_link": "https://vignette.id/external/pay/eo_UwMWPQcOF1LhlmMU"
    }
  ]
}

json

application/json

Create External Order

POST

https://sandbox-api.vignette.id

/public/external-orders

Create a partner (external) payment order. Vignette ID generates a hosted payment_link the partner shows to the customer, then reports status changes to the callback_url webhook.

⚠️ Rate limit policy applies to this endpoint Check Rate Limits

Create External Order › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Content-Type

string · enum · required

Specifies the format of the request body. Must be 'application/json' for requests with a JSON body.

Enum values:

application/json

Default: application/json

Create External Order › Request Body

reference_id

string · minLength: 1 · required

Order identifier in the Partner system. Must be unique per partner. Used to fetch the order later via Get External Order.

product

string · minLength: 1 · required

Product slug on the partner side. Free-form value, e.g. esim.

amount

number · required

Order amount in major units of currency (decimal, not minor units). For example 22.99 means 22 euro 99 cents when currency is EUR.

currency

string · minLength: 1 · required

ISO 4217 currency code of the order amount, e.g. EUR, UAH, PLN.

email

string · email · required

Customer email. Payment receipts and notifications are sent to this address.

allowed_payment_providers

string[] · minItems: 1 · unique · required

Payment providers the customer is allowed to pay with. The final provider is chosen at checkout.

Enum values:

monobank

stripe

paypal

callback_url

string · uri · required

Server-to-server webhook URL. Vignette ID sends order status updates (paid / completed / failed) to this endpoint.

description

string

Human-readable description of the order. Shown to the user on the payment page.

success_url

string · uri

URL the customer is redirected to after a successful payment. If omitted, no redirect happens — the payment modal shows a success animation instead.

cancel_url

string · uri

URL the customer is redirected to after a cancelled payment. If omitted, no redirect happens — the payment modal shows a cancel animation instead.

subaccount

string

Partner sub-account name. Lets a partner split orders across different UIs / apps / branches.

open_order_details_by_default

boolean

When true, the payment page opens with the order details section expanded by default.

expires_in

integer · min: 60 · max: 3600

Lifetime of the order in whole seconds, counted from creation. After it elapses, the payment_link stops working. Whole number between 60 and 3600. Defaults to 900 (15 minutes).

Default: 900

Create External Order › Responses

External order created

ExternalOrderObject

error

object | null

ExternalOrderResult

POST/public/external-orders

curl https://sandbox-api.vignette.id/public/external-orders \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "reference_id": "esim-9",
  "product": "esim",
  "description": "Esim",
  "amount": 22.99,
  "currency": "EUR",
  "email": "customer@example.com",
  "allowed_payment_providers": [
    "monobank"
  ],
  "callback_url": "https://vignette.id/api/track/events/webhook",
  "subaccount": "web-shop",
  "open_order_details_by_default": true
}'

Example Request Body

{
  "reference_id": "esim-9",
  "product": "esim",
  "description": "Esim",
  "amount": 22.99,
  "currency": "EUR",
  "email": "customer@example.com",
  "allowed_payment_providers": [
    "monobank"
  ],
  "callback_url": "https://vignette.id/api/track/events/webhook",
  "subaccount": "web-shop",
  "open_order_details_by_default": true
}

json

application/json

Example Responses

{
  "error": null,
  "result": {
    "id": "eo_KOyLSjN3wNub1SJH",
    "reference_id": "esim-9",
    "status": "CREATED",
    "product": "esim",
    "description": "Esim",
    "amount": 22.99,
    "currency": "EUR",
    "email": "customer@example.com",
    "subaccount": "web-shop",
    "payment_provider": null,
    "allowed_payment_providers": [
      "monobank"
    ],
    "callback_url": "https://vignette.id/api/track/events/webhook",
    "success_url": null,
    "cancel_url": null,
    "open_order_details_by_default": true,
    "is_sandbox": true,
    "error_message": null,
    "created_at": "2026-07-23T12:42:53.215+00:00",
    "paid_at": null,
    "completed_at": null,
    "payment_link": "https://vignette.id/external/pay/eo_KOyLSjN3wNub1SJH",
    "payments": [
      {
        "provider": "monobank",
        "status": "PENDING"
      }
    ]
  }
}

json

application/json

Get External Order

GET

https://sandbox-api.vignette.id

/public/external-orders/{reference_id}

Returns a single external order by its Partner-side reference_id.

⚠️ Rate limit policy applies to this endpoint Check Rate Limits

Get External Order › path Parameters

reference_id

string · required

reference_id of the external order in the Partner system (the value sent on creation).

Get External Order › query Parameters

bug_report

boolean

Use with all endpoints to inform us for bugs in API

Default: false

Get External Order › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get External Order › Responses

External order details

ExternalOrderObject

error

object | null

ExternalOrderResult

GET/public/external-orders/{reference_id}

curl https://sandbox-api.vignette.id/public/external-orders/:reference_id \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "error": null,
  "result": {
    "id": "eo_KOyLSjN3wNub1SJH",
    "external_order_id": "partner-order-4716",
    "status": "CREATED",
    "product": "my-product",
    "description": "Testing my product",
    "amount": 25.99,
    "currency": "EUR",
    "email": "vezhdelit@gmail.com",
    "subaccount": "web-shop",
    "payment_provider": null,
    "allowed_payment_providers": [
      "stripe"
    ],
    "callback_url": "https://vignette.id/api/track/events/sandbox/webhook",
    "success_url": null,
    "cancel_url": null,
    "is_sandbox": true,
    "error_message": null,
    "created_at": "2026-07-23T12:42:53.215+00:00",
    "paid_at": null,
    "completed_at": null,
    "payment_link": "http://localhost:3000/external/pay/eo_KOyLSjN3wNub1SJH",
    "payments": [
      {
        "provider": "stripe",
        "status": "PENDING"
      }
    ]
  }
}

json

application/json

Cancel External Order

POST

https://sandbox-api.vignette.id

/public/external-orders/{id}/cancel

Cancels an external order and stops its payment_link from working. Accepts either the Vignette ID order id (eo_...) or the partner-side reference_id in the path.

The call is idempotent — cancelling an already-cancelled order returns 200 with the same order. A cancelled order cannot be restored; create a new one instead.

On success the order moves to status: CANCELED and an EXTERNAL_ORDER_STATUS_CHANGED webhook with status: CANCELED is delivered to the order's callback_url. An order that has already been paid cannot be cancelled (409 external_order_not_cancelable) — issue a refund instead.

⚠️ Rate limit policy applies to this endpoint Check Rate Limits

Cancel External Order › path Parameters

id

string · required

Order identifier. Accepts either the Vignette ID order id (eo_...) or the partner-side reference_id sent on creation.

Cancel External Order › query Parameters

bug_report

boolean

Use with all endpoints to inform us for bugs in API

Default: false

Cancel External Order › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Cancel External Order › Request Body optional

reason

string · maxLength: 255

Free-form cancellation reason, stored with the order. Up to 255 characters.

Cancel External Order › Responses

External order cancelled (or already cancelled — idempotent)

ExternalOrderObject

error

object | null

ExternalOrderResult

POST/public/external-orders/{id}/cancel

curl https://sandbox-api.vignette.id/public/external-orders/:id/cancel \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "reason": "wrong customer data"
}'

Example Request Body

{
  "reason": "wrong customer data"
}

json

application/json

Example Responses

{
  "error": null,
  "result": {
    "id": "eo_KOyLSjN3wNub1SJH",
    "reference_id": "esim-9",
    "status": "CANCELED",
    "product": "esim",
    "description": "Esim",
    "amount": 22.99,
    "currency": "EUR",
    "email": "customer@example.com",
    "subaccount": "web-shop",
    "payment_provider": null,
    "allowed_payment_providers": [
      "monobank"
    ],
    "callback_url": "https://vignette.id/api/track/events/webhook",
    "success_url": null,
    "cancel_url": null,
    "open_order_details_by_default": true,
    "is_sandbox": true,
    "error_message": null,
    "created_at": "2026-07-23T12:42:53.215+00:00",
    "paid_at": null,
    "completed_at": null,
    "canceled_at": "2026-07-23T13:05:11.482+00:00",
    "payment_link": "https://vignette.id/external/pay/eo_KOyLSjN3wNub1SJH",
    "payments": [
      {
        "provider": "monobank",
        "status": "CANCELED"
      }
    ]
  }
}

json

application/json

Orders List Endpoints Extended List Endpoints