payment-links

Stable. Describes behaviour that is built and covered by tests in this repository.

GET `/v1/payment-links` #

List payment links

Parameters

Name	In	Type	Description
`kind`	query	`invoice` \| `adhoc`
`status`	query	`active` \| `paid` \| `expired` \| `revoked`
`invoice_id`	query	string · uuid
`customer`	query	string	The customer's external id
`page_size`	query	integer
`page_token`	query	string

Responses

Status	Meaning	Body
`200`	OK	ListPaymentLinksResponse
`400`	Error envelope	Error

Example response

{
  "links": [
    {
      "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "kind": "invoice",
      "status": "active",
      "pack_id": "string",
      "quantity": 1,
      "credits": "string",
      "promotion_code": "string",
      "required_contracts": [
        "distance_sales"
      ],
      "invoice_id": "string",
      "customer_external_id": "string",
      "single_use": false,
      "amount_minor": "string",
      "currency": "string",
      "description": "string",
      "create_time": "2026-11-03T10:15:00Z",
      "expire_time": "2026-11-03T10:15:00Z",
      "revoke_time": null,
      "paid_count": 1,
      "last_paid_time": null,
      "use_count": 1,
      "idempotency_key": "string"
    }
  ],
  "next_page_token": "string"
}

curl

curl -X GET https://YOUR-API-ADDRESS/v1/payment-links \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

POST `/v1/payment-links` #

Make a payment link for an open invoice, or ad hoc for a fixed amount

kind: invoice (needs invoice_id, a finalized unpaid invoice) or kind: adhoc (needs amount_minor, optionally currency — the tenant's by default — description and a customer_external_id; the invoice is made when the customer first presses Continue). The token is returned once. Idempotency-Key (or idempotency_key) makes a retry return the link made the first time, without the token (replayed: true); the same key with other parameters is refused. Single-use links stop after one paid invoice; a reusable ad-hoc link makes one invoice per use.

Request body

Field	Type	Description
`kind`	`invoice` \| `adhoc` \| `credit_pack`	Default: invoice when invoice_id is set, credit_pack when pack_id is set, else adhoc
`invoice_id`	string · uuid
`pack_id`	string · uuid	credit_pack: the active credit pack to sell. Its price and currency become the link's amount; they are never taken from the request
`quantity`	integer	credit_pack: how many packs one payment buys (default 1)
`amount_minor`	string · int64	adhoc: a positive int64 in minor units (a string or a number)
`currency`	string	adhoc: ISO 4217; the tenant's currency when empty
`description`	string	adhoc: what it is for; printed on the invoice
`customer_external_id`	string	adhoc: make the invoice out to this customer. credit_pack: required, the customer who receives the credits
`single_use`	boolean	Default true for adhoc, false for invoice
`promotion_code`	string	adhoc and credit_pack, optional: a promotion code the payer gets without typing it (a one-off invoice with a discount). Checked against the link's own amount now (a coupon.* error if it does not work); claimed when the payer continues. An invoice that exists is not changed, so a kind invoice link takes none
`required_contracts`	array of `distance_sales` \| `pre_info` \| `tos` \| `privacy`	Optional: the agreements the payer must accept on this link's page. The list replaces the seller's tenant-wide required_kinds for this link (it does not add to it); empty or absent: the setting applies. The texts must be published before the link is used, or the page offers no way to pay. An ad-hoc link hands its list to the invoice link the payer continues on. 400 billing.payment_link.bad_required_contracts for an unknown kind or one named twice
`expires_in_days`	integer	Default 30 for adhoc, 90 for invoice
`idempotency_key`	string

Example

{}

Responses

Status	Meaning	Body
`200`	Replayed: the link made the first time, without the token	CreatedPaymentLink
`201`	Created	CreatedPaymentLink
`400`	Error envelope	Error
`404`	Error envelope	Error
`409`	Error envelope	Error

Example response

{
  "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
  "kind": "invoice",
  "status": "active",
  "pack_id": "string",
  "quantity": 1,
  "credits": "string",
  "promotion_code": "string",
  "required_contracts": [
    "distance_sales"
  ],
  "invoice_id": "string",
  "customer_external_id": "string",
  "single_use": false,
  "amount_minor": "string",
  "currency": "string",
  "description": "string",
  "create_time": "2026-11-03T10:15:00Z",
  "expire_time": "2026-11-03T10:15:00Z",
  "revoke_time": null,
  "paid_count": 1,
  "last_paid_time": null,
  "use_count": 1,
  "idempotency_key": "string",
  "token": "string",
  "url": "string",
  "replayed": false
}

curl

curl -X POST https://YOUR-API-ADDRESS/v1/payment-links \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

GET `/v1/payment-links/{id}` #

One payment link

Parameters

Name	In	Type	Description
`id` required	path	string · uuid

Responses

Status	Meaning	Body
`200`	OK	PaymentLink
`404`	Error envelope	Error

Example response

{
  "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
  "kind": "invoice",
  "status": "active",
  "pack_id": "string",
  "quantity": 1,
  "credits": "string",
  "promotion_code": "string",
  "required_contracts": [
    "distance_sales"
  ],
  "invoice_id": "string",
  "customer_external_id": "string",
  "single_use": false,
  "amount_minor": "string",
  "currency": "string",
  "description": "string",
  "create_time": "2026-11-03T10:15:00Z",
  "expire_time": "2026-11-03T10:15:00Z",
  "revoke_time": null,
  "paid_count": 1,
  "last_paid_time": null,
  "use_count": 1,
  "idempotency_key": "string"
}

curl

curl -X GET https://YOUR-API-ADDRESS/v1/payment-links/<id> \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

DELETE `/v1/payment-links/{id}` #

Revoke a payment link

The link and the invoice links it handed out stop working. Unpaid invoices made from an ad-hoc link are voided; paid ones are untouched. Revoking twice is not an error.

Parameters

Name	In	Type	Description
`id` required	path	string · uuid

Responses

Status	Meaning	Body
`200`	OK	PaymentLink
`404`	Error envelope	Error

Example response

{
  "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
  "kind": "invoice",
  "status": "active",
  "pack_id": "string",
  "quantity": 1,
  "credits": "string",
  "promotion_code": "string",
  "required_contracts": [
    "distance_sales"
  ],
  "invoice_id": "string",
  "customer_external_id": "string",
  "single_use": false,
  "amount_minor": "string",
  "currency": "string",
  "description": "string",
  "create_time": "2026-11-03T10:15:00Z",
  "expire_time": "2026-11-03T10:15:00Z",
  "revoke_time": null,
  "paid_count": 1,
  "last_paid_time": null,
  "use_count": 1,
  "idempotency_key": "string"
}

curl

curl -X DELETE https://YOUR-API-ADDRESS/v1/payment-links/<id> \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

Models

CreatePaymentLinkRequest

Field	Type	Description
`kind`	`invoice` \| `adhoc` \| `credit_pack`	Default: invoice when invoice_id is set, credit_pack when pack_id is set, else adhoc
`invoice_id`	string · uuid
`pack_id`	string · uuid	credit_pack: the active credit pack to sell. Its price and currency become the link's amount; they are never taken from the request
`quantity`	integer	credit_pack: how many packs one payment buys (default 1)
`amount_minor`	string · int64	adhoc: a positive int64 in minor units (a string or a number)
`currency`	string	adhoc: ISO 4217; the tenant's currency when empty
`description`	string	adhoc: what it is for; printed on the invoice
`customer_external_id`	string	adhoc: make the invoice out to this customer. credit_pack: required, the customer who receives the credits
`single_use`	boolean	Default true for adhoc, false for invoice
`promotion_code`	string	adhoc and credit_pack, optional: a promotion code the payer gets without typing it (a one-off invoice with a discount). Checked against the link's own amount now (a coupon.* error if it does not work); claimed when the payer continues. An invoice that exists is not changed, so a kind invoice link takes none
`required_contracts`	array of `distance_sales` \| `pre_info` \| `tos` \| `privacy`	Optional: the agreements the payer must accept on this link's page. The list replaces the seller's tenant-wide required_kinds for this link (it does not add to it); empty or absent: the setting applies. The texts must be published before the link is used, or the page offers no way to pay. An ad-hoc link hands its list to the invoice link the payer continues on. 400 billing.payment_link.bad_required_contracts for an unknown kind or one named twice
`expires_in_days`	integer	Default 30 for adhoc, 90 for invoice
`idempotency_key`	string

CreatedPaymentLink

Field	Type	Description
`id` required	string · uuid
`kind` required	`invoice` \| `adhoc` \| `credit_pack`
`status` required	`active` \| `paid` \| `expired` \| `revoked`	paid: a single-use link that was paid
`pack_id` required	string	kind credit_pack: the pack sold
`quantity` required	integer	kind credit_pack: how many packs one use buys
`credits` required	string · int64	kind credit_pack: the credits one paid use grants (the pack's credits times the quantity, frozen when the link was made); int64 as a string
`promotion_code` required	string	The code the seller chose for the link (adhoc and credit_pack): applied when the payer continues, unless the payer types another
`required_contracts` required	array of `distance_sales` \| `pre_info` \| `tos` \| `privacy`	The agreements the payer accepts on this link's page instead of the seller's tenant-wide setting (GET /v1/contracts/settings); empty: the setting applies
`invoice_id` required	string	kind invoice: the invoice; empty for an ad-hoc link (its invoices are made on use)
`customer_external_id` required	string
`single_use` required	boolean
`amount_minor` required	string · int64	kind adhoc: int64 minor units as a string
`currency` required	string
`description` required	string
`create_time` required	string · date-time
`expire_time` required	string · date-time
`revoke_time` required	string,null · date-time
`paid_count` required	integer	Invoices paid through the link
`last_paid_time` required	string,null · date-time
`use_count` required	integer	Invoices the link created (ad hoc)
`idempotency_key` required	string
`token` required	string	The secret part of the link; shown once, empty on a replay
`url` required	string	Absolute when the deployment has a public address set; empty on a replay
`replayed` required	boolean

Error

Field	Type	Description
`error` required	object

ListPaymentLinksResponse

Field	Type	Description
`links` required	array of PaymentLink
`next_page_token` required	string

PaymentLink

Field	Type	Description
`id` required	string · uuid
`kind` required	`invoice` \| `adhoc` \| `credit_pack`
`status` required	`active` \| `paid` \| `expired` \| `revoked`	paid: a single-use link that was paid
`pack_id` required	string	kind credit_pack: the pack sold
`quantity` required	integer	kind credit_pack: how many packs one use buys
`credits` required	string · int64	kind credit_pack: the credits one paid use grants (the pack's credits times the quantity, frozen when the link was made); int64 as a string
`promotion_code` required	string	The code the seller chose for the link (adhoc and credit_pack): applied when the payer continues, unless the payer types another
`required_contracts` required	array of `distance_sales` \| `pre_info` \| `tos` \| `privacy`	The agreements the payer accepts on this link's page instead of the seller's tenant-wide setting (GET /v1/contracts/settings); empty: the setting applies
`invoice_id` required	string	kind invoice: the invoice; empty for an ad-hoc link (its invoices are made on use)
`customer_external_id` required	string
`single_use` required	boolean
`amount_minor` required	string · int64	kind adhoc: int64 minor units as a string
`currency` required	string
`description` required	string
`create_time` required	string · date-time
`expire_time` required	string · date-time
`revoke_time` required	string,null · date-time
`paid_count` required	integer	Invoices paid through the link
`last_paid_time` required	string,null · date-time
`use_count` required	integer	Invoices the link created (ad hoc)
`idempotency_key` required	string

payment-links

GET /v1/payment-links #

Parameters

Responses

POST /v1/payment-links #

Request body

Responses

GET /v1/payment-links/{id} #

Parameters

Responses

DELETE /v1/payment-links/{id} #

Parameters

Responses

Models

CreatePaymentLinkRequest

CreatedPaymentLink

Error

ListPaymentLinksResponse

PaymentLink

GET `/v1/payment-links` #

POST `/v1/payment-links` #

GET `/v1/payment-links/{id}` #

DELETE `/v1/payment-links/{id}` #