contracts

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

GET `/v1/contracts/versions` #

The versions of the agreements you present to your customers, newest first

A version is one edition of an agreement (distance sales, pre-information, terms, privacy) in one or more languages. Needs contracts:read.

Parameters

Name	In	Type	Description
`kind`	query	ContractKind
`audience`	query	ContractAudience

Responses

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

Example response

{
  "versions": [
    {
      "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "kind": "distance_sales",
      "audience": "consumer",
      "number": 1,
      "material": false,
      "bodies": {},
      "sha256": "string",
      "note": "string",
      "author": "string",
      "create_time": "2026-11-03T10:15:00Z",
      "variables": [
        "string"
      ],
      "current": false,
      "has_template_notice": false
    }
  ]
}

curl

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

POST `/v1/contracts/versions` #

Publish the next version of an agreement

A version cannot be edited: this adds the next one to the series of (kind, audience), which becomes the one customers see. The texts are restricted markdown (# headings, - and 1. lists, **bold**, blank-line paragraphs; raw HTML is shown as text) with {{variable}} placeholders from a fixed list (seller_name, seller_address, seller_tax_id, seller_tax_office, seller_mersis, customer_name, customer_email, customer_address, order_description, order_total, order_currency, date). A material version asks customers who accepted an earlier one to accept again; a minor one does not (the first version of a series is always material). Payrudder supplies starter texts for Turkish and English that must be reviewed by a lawyer; it does not say any text is legally sufficient. Error keys plans.contract.unknown_variable, plans.contract.body_required. Needs contracts:write.

Request body

Field	Type	Description
`kind` required	ContractKind
`audience`	ContractAudience	A business customer gets the business series when one is published, else the consumer's.
`bodies` required	object
`material`	boolean
`note`	string

Example

{
  "kind": "distance_sales",
  "bodies": {}
}

Responses

Status	Meaning	Body
`201`	Created	ContractVersion
`400`	Error envelope	Error

Example response

{
  "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
  "kind": "distance_sales",
  "audience": "consumer",
  "number": 1,
  "material": false,
  "bodies": {},
  "sha256": "string",
  "note": "string",
  "author": "string",
  "create_time": "2026-11-03T10:15:00Z",
  "variables": [
    "string"
  ],
  "current": false,
  "has_template_notice": false
}

curl

curl -X POST https://YOUR-API-ADDRESS/v1/contracts/versions \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"distance_sales","bodies":{}}'

GET `/v1/contracts/versions/{id}` #

One version of an agreement

Parameters

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

Responses

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

Example response

{
  "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
  "kind": "distance_sales",
  "audience": "consumer",
  "number": 1,
  "material": false,
  "bodies": {},
  "sha256": "string",
  "note": "string",
  "author": "string",
  "create_time": "2026-11-03T10:15:00Z",
  "variables": [
    "string"
  ],
  "current": false,
  "has_template_notice": false
}

curl

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

POST `/v1/contracts/preview` #

Render a text the way a customer would see it, with sample values

Reports the variables the text uses and any that do not exist. Nothing is stored.

Request body

Field	Type	Description
`body` required	string
`locale`	string

Example

{
  "body": "string"
}

Responses

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

Example response

{
  "html": "string",
  "variables": [
    "string"
  ],
  "unknown_variables": [
    "string"
  ]
}

curl

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

GET `/v1/contracts/starter` #

The starter text of an agreement in Turkish or English

A template to start from, with a notice on top that it is not legal advice and must be reviewed by a lawyer before use. There is no starter text in other languages (error key plans.contract.no_starter).

Parameters

Name	In	Type
`kind` required	query	ContractKind
`locale` required	query	`tr` \| `en`
`audience`	query	ContractAudience

Responses

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

Example response

{
  "body": "string",
  "locale": "tr"
}

curl

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

GET `/v1/contracts/settings` #

Which agreements are required, whether the service starts at once, and how long evidence is kept

Responses

Status	Meaning	Body
`200`	OK	ContractSettings

Example response

{
  "required_kinds": [
    "distance_sales"
  ],
  "immediate_start": false,
  "retention_months": 12,
  "published_kinds": [
    "distance_sales"
  ],
  "update_time": "2026-11-03T10:15:00Z",
  "withdrawal_refund": "full",
  "renewal_notice_days": 0,
  "renewal_cancel_texts": {},
  "withdrawal_function": false
}

curl

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

PUT `/v1/contracts/settings` #

Change which agreements are required

While required_kinds is not empty, no subscription is created for a customer who has not accepted the current version of each of them (error key plans.contract.not_accepted), and a hosted payment page asks for them next to the pay button. A kind can be required once a version of it is published (plans.contract.kind_unpublished). Renewals and dunning charges are never held back. With immediate_start, a consumer is asked for the request to start at once and the acknowledgement of losing the right of withdrawal as two separate boxes (plans.contract.consent_required). retention_months (12 to 120, default 36; 0 keeps the value) is how long the IP address and user agent of an acceptance are kept; the rest of the record stays.

Request body

Field	Type	Description
`required_kinds`	array of ContractKind
`immediate_start`	boolean
`retention_months`	integer · int32	0 keeps the current value.
`withdrawal_refund`	`full` \| `none`	Empty keeps the current value.
`renewal_notice_days`	integer · int32	Absent keeps the current value; 0 switches the notice off.
`renewal_cancel_texts`	object	A language sent with a text sets it, with an empty text removes it; a language not sent keeps its text.
`withdrawal_function`	boolean	Absent keeps the current value.

Example

{}

Responses

Status	Meaning	Body
`200`	OK	ContractSettings
`400`	Error envelope	Error
`409`	Error envelope	Error

Example response

{
  "required_kinds": [
    "distance_sales"
  ],
  "immediate_start": false,
  "retention_months": 12,
  "published_kinds": [
    "distance_sales"
  ],
  "update_time": "2026-11-03T10:15:00Z",
  "withdrawal_refund": "full",
  "renewal_notice_days": 0,
  "renewal_cancel_texts": {},
  "withdrawal_function": false
}

curl

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

Models

ContractAudience

consumer | business

ContractKind

distance_sales | pre_info | tos | privacy

ContractSettings

Field	Type	Description
`required_kinds` required	array of ContractKind
`immediate_start` required	boolean
`retention_months` required	integer · int32
`published_kinds` required	array of ContractKind	Kinds that have a published consumer version.
`update_time` required	string · date-time
`withdrawal_refund` required	`full` \| `none`	What accepting a withdrawal does about the money. full (the default) asks billing for a refund of the invoice to the card; none leaves it to the seller. The seller decides the withdrawal either way.
`renewal_notice_days` required	integer · int32	How many days before a renewal the customer is mailed the renewal notice (price, date, how to cancel). 0 is off; default 7. Only for a subscription whose fixed fee is invoiced in advance and a customer who accepted an agreement.
`renewal_cancel_texts` required	object	Language (en, tr, de, fr, es, ar) to the seller's own words on how to cancel, printed in the renewal notice.
`withdrawal_function` required	boolean	Consumers can withdraw from a contract on the hosted pages and are sent an acknowledgement (Directive 2011/83/EU art. 11a). Only while agreements are required. Default on.

ContractVersion

Field	Type	Description
`id` required	string · uuid
`kind` required	ContractKind
`audience` required	ContractAudience	A business customer gets the business series when one is published, else the consumer's.
`number` required	integer · int32
`material` required	boolean	Customers who accepted an earlier version are asked again.
`bodies` required	object	Language (en, tr, de, fr, es, ar) to the text.
`sha256` required	string	Hex sha256 over the kind, audience and every text.
`note` required	string
`author` required	string
`create_time` required	string · date-time
`variables` required	array of string
`current` required	boolean	The newest version of its series.
`has_template_notice` required	boolean	A text still carries the starter notice (template, have a lawyer review).

Error

Field	Type	Description
`error` required	object

GetContractStarterResponse

Field	Type	Description
`body` required	string
`locale` required	`tr` \| `en`

ListContractVersionsResponse

Field	Type	Description
`versions` required	array of ContractVersion

PreviewContractRequest

Field	Type	Description
`body` required	string
`locale`	string

PreviewContractResponse

Field	Type	Description
`html` required	string	Safe HTML; the variables are shown with sample values inside <mark>.
`variables` required	array of string
`unknown_variables` required	array of string

PublishContractVersionRequest

Field	Type	Description
`kind` required	ContractKind
`audience`	ContractAudience	A business customer gets the business series when one is published, else the consumer's.
`bodies` required	object
`material`	boolean
`note`	string

SetContractSettingsRequest

Field	Type	Description
`required_kinds`	array of ContractKind
`immediate_start`	boolean
`retention_months`	integer · int32	0 keeps the current value.
`withdrawal_refund`	`full` \| `none`	Empty keeps the current value.
`renewal_notice_days`	integer · int32	Absent keeps the current value; 0 switches the notice off.
`renewal_cancel_texts`	object	A language sent with a text sets it, with an empty text removes it; a language not sent keeps its text.
`withdrawal_function`	boolean	Absent keeps the current value.

contracts

GET /v1/contracts/versions #

Parameters

Responses

POST /v1/contracts/versions #

Request body

Responses

GET /v1/contracts/versions/{id} #

Parameters

Responses

POST /v1/contracts/preview #

Request body

Responses

GET /v1/contracts/starter #

Parameters

Responses

GET /v1/contracts/settings #

Responses

PUT /v1/contracts/settings #

Request body

Responses

Models

ContractAudience

ContractKind

ContractSettings

ContractVersion

Error

GetContractStarterResponse

ListContractVersionsResponse

PreviewContractRequest

PreviewContractResponse

PublishContractVersionRequest

SetContractSettingsRequest

GET `/v1/contracts/versions` #

POST `/v1/contracts/versions` #

GET `/v1/contracts/versions/{id}` #

POST `/v1/contracts/preview` #

GET `/v1/contracts/starter` #

GET `/v1/contracts/settings` #

PUT `/v1/contracts/settings` #