sandbox

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

POST `/v1/sandbox/close-period` #

Sandbox only — close a period now and run the real billing flow

Lowers the period's cutoff to now + 5 s, then billing runs exactly as at month end: watermark (starting 30 s after the new cutoff), rating, numbering (SBX-…) and the invoice saga with mock payments. Poll GET /v1/invoices. period defaults to the current period. Live keys get 403.

Request body

Field	Type	Description
`period`	string

Example

{}

Responses

Status	Meaning	Body
`202`	Accepted	BillingRun
`400`	Error envelope	Error
`403`	Error envelope	Error

Example response

{
  "tenant_id": "string",
  "period_id": "string",
  "status": "RUN_STATUS_SCHEDULED",
  "cutoff_time": "2026-11-03T10:15:00Z",
  "invoice_count": 1,
  "last_error": "string",
  "generation": 1,
  "start_time": "2026-11-03T10:15:00Z",
  "complete_time": "2026-11-03T10:15:00Z"
}

curl

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

POST `/v1/sandbox/customers/{external_id}/payment-scenario` #

Sandbox only — choose the mock payment outcome for a customer

{"scenario": "declined"} sets pm_sandbox_declined. Live keys get 403.

Parameters

Name	In	Type	Description
`external_id` required	path	string

Request body

Field	Type	Description
`scenario` required	`success` \| `declined` \| `insufficient_funds_once` \| `error_then_success` \| `timeout_committed` \| `timeout_not_committed`

Example

{
  "scenario": "success"
}

Responses

Status	Meaning	Body
`200`	OK	Customer
`403`	Error envelope	Error

Example response

{
  "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
  "external_id": "string",
  "name": "string",
  "email": "string",
  "payment_method": "string",
  "create_time": "2026-11-03T10:15:00Z",
  "country": "string",
  "billing_currency": "string",
  "address": {
    "line1": "string",
    "line2": "string",
    "city": "string",
    "region": "string",
    "postal_code": "string",
    "country": "string"
  },
  "tax_id": "string",
  "tax_office": "string",
  "e_invoice_registered": false,
  "locale": "string",
  "customer_type": "string",
  "block_reason": "string",
  "block_category": "string",
  "service_suspended": false,
  "phone": "string",
  "tax_id_warning": "string"
}

curl

curl -X POST https://YOUR-API-ADDRESS/v1/sandbox/customers/<external_id>/payment-scenario \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scenario":"success"}'

GET `/v1/sandbox/scenarios` #

The payment scenarios of a sandbox customer

What each pm_sandbox_* payment method does. Sandbox keys only.

Responses

Status	Meaning	Body
`200`	OK	SandboxScenariosResponse
`403`	Error envelope	Error

Example response

{
  "scenarios": [
    {
      "scenario": "declined",
      "payment_method": "pm_sandbox_declined",
      "outcome": "paid",
      "description": "string"
    }
  ]
}

curl

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

POST `/v1/sandbox/invoices/{id}/simulate` #

Run an invoice's payment again under a scenario

Sets the invoice's customer to the scenario (it stays their payment method) and retries the invoice's payment. When the payment cannot run again now (paid, or in progress) the scenario is still set and retried is false with the reason in retry_error. Sandbox keys only.

Parameters

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

Request body

Field	Type	Description
`scenario` required	string	A name from /v1/sandbox/scenarios, with or without the pm_sandbox_ prefix.

Example

{
  "scenario": "string"
}

Responses

Status	Meaning	Body
`200`	OK	SandboxSimulateInvoiceResponse
`400`	Error envelope	Error
`403`	Error envelope	Error
`404`	Error envelope	Error

Example response

{
  "invoice_id": "string",
  "customer_external_id": "string",
  "scenario": "string",
  "payment_method": "string",
  "retried": false
}

curl

curl -X POST https://YOUR-API-ADDRESS/v1/sandbox/invoices/<id>/simulate \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scenario":"string"}'

Models

Address

Field	Type	Description
`line1` required	string
`line2` required	string
`city` required	string
`region` required	string	State, province or county
`postal_code` required	string
`country` required	string	ISO 3166-1 alpha-2

BillingRun

Field	Type	Description
`tenant_id` required	string
`period_id` required	string
`status` required	`RUN_STATUS_SCHEDULED` \| `RUN_STATUS_WAITING_WATERMARK` \| `RUN_STATUS_RATING` \| `RUN_STATUS_INVOICING` \| `RUN_STATUS_COMPLETED` \| `RUN_STATUS_FAILED`
`cutoff_time` required	string · date-time
`invoice_count` required	integer
`last_error` required	string
`generation` required	integer
`start_time` required	string · date-time
`complete_time` required	string · date-time

Customer

Field	Type	Description
`id` required	string · uuid
`external_id` required	string
`name` required	string
`email` required	string
`payment_method` required	string
`create_time` required	string · date-time
`country` required	string	ISO 3166-1 alpha-2
`billing_currency` required	string	ISO 4217
`address` required	any
`tax_id` required	string
`tax_office` required	string
`e_invoice_registered` required	boolean
`locale` required	string	The language of the customer's mails, receipts and payment pages: en, tr, de, fr, es or ar. Empty is the browser's language (pages) and English (mails).
`customer_type` required	string	individual (a person) or business (a taxpayer with a tax id). Empty is unknown.
`block_time`	string · date-time	Set while the customer is blocked: no new subscription, plan change or purchase (existing subscriptions run on). A block whose blocked_until has passed has ended, whatever this says.
`block_reason` required	string	The seller's own note on the block; never shown to the customer.
`block_category` required	string	Why: fraud, chargeback, abuse, request or other; empty when none was given.
`blocked_until`	string · date-time	When the block ends by itself; absent: until it is lifted.
`service_suspended` required	boolean	The block also suspends the customer's service: every entitlement check answers allowed false. Read it with block_time and blocked_until, it holds only while the block does.
`phone` required	string	The customer's mobile number as E.164 (+905321234567); empty when none.
`tax_id_validated_at`	string · date-time	When tax_id last passed the local check (a TCKN or VKN checksum, the shape of a European VAT id). Not a registry lookup: no VIES, no GİB query. Absent when the id is empty or not recognised.
`tax_id_warning` required	string	One of tr_individual, tr_business, tr_any, tr_is_tckn, tr_is_vkn, eu_vat, or empty. A hint, never a refusal: the id does not look like the kind of number this customer should have (tr_individual: not a TCKN; tr_business: not a VKN; tr_any: neither; tr_is_tckn: a business was given a TCKN; tr_is_vkn: an individual was given a VKN; eu_vat: a business in the EU has no VAT id of its country's shape). Worked out from the stored id, country and customer_type, so it follows a change of any of them. Empty: nothing to say.

Error

Field	Type	Description
`error` required	object

SandboxClosePeriodRequest

Field	Type	Description
`period`	string

SandboxScenariosResponse

Field	Type	Description
`scenarios` required	array of SandboxScenariosScenario

SandboxScenariosScenario

Field	Type	Description
`scenario` required	string
`payment_method` required	string
`outcome` required	`paid` \| `uncollectible` \| `paid_after_retry` \| `paid_after_status_query` \| `paid_after_recharge`
`default`	boolean
`description` required	string

SandboxSimulateInvoiceRequest

Field	Type	Description
`scenario` required	string	A name from /v1/sandbox/scenarios, with or without the pm_sandbox_ prefix.

SandboxSimulateInvoiceResponse

Field	Type	Description
`invoice_id` required	string
`customer_external_id` required	string
`scenario` required	string
`payment_method` required	string
`retried` required	boolean
`retry_error`	string

SetPaymentScenarioRequest

Field	Type	Description
`scenario` required	`success` \| `declined` \| `insufficient_funds_once` \| `error_then_success` \| `timeout_committed` \| `timeout_not_committed`

sandbox

POST /v1/sandbox/close-period #

Request body

Responses

POST /v1/sandbox/customers/{external_id}/payment-scenario #

Parameters

Request body

Responses

GET /v1/sandbox/scenarios #

Responses

POST /v1/sandbox/invoices/{id}/simulate #

Parameters

Request body

Responses

Models

Address

BillingRun

Customer

Error

SandboxClosePeriodRequest

SandboxScenariosResponse

SandboxScenariosScenario

SandboxSimulateInvoiceRequest

SandboxSimulateInvoiceResponse

SetPaymentScenarioRequest

POST `/v1/sandbox/close-period` #

POST `/v1/sandbox/customers/{external_id}/payment-scenario` #

GET `/v1/sandbox/scenarios` #

POST `/v1/sandbox/invoices/{id}/simulate` #