Regulatory Filings quickstart

Use a secret API key from your backend and an account authorized for that key. Publishable keys cannot access these operations. Requests use the key's test or live mode; disclosures are isolated by account and mode. Set the variables below to your own values and keep the secret key out of client-side code.

For retrieval and download, use Paypercut-Account to select the account when your API key can access multiple accounts. X-Paypercut-Account is also accepted.

1. Discover capabilities

export PAYPERCUT_SECRET_KEY='YOUR_SECRET_KEY'
export ACCOUNT_ID='YOUR_ACCOUNT_ID'
curl --fail-with-body "https://api.paypercut.io/v1/accounts/$ACCOUNT_ID/regulatory_capabilities" \
  -H "Authorization: Bearer $PAYPERCUT_SECRET_KEY"

An illustrative response for a Bulgarian account is:

{
  "object": "list",
  "data": [{
    "id": "bg_nra_ecommerce",
    "object": "regulatory_capability",
    "country": "BG",
    "authority": {"id": "bg_nra", "name": "National Revenue Agency"},
    "regulation": "ordinance_h18",
    "forms": [{"id": "bg_nra_appendix_33", "name": "Electronic Store Declaration"}],
    "supported_operations": ["disclosure_generation"]
  }]
}

2. Create a disclosure

Choose an available capability and a unique idempotency key for this snapshot. form and form_version are optional; when omitted, the supported selection is used. Save the returned id.

export IDEMPOTENCY_KEY="$(uuidgen)"
curl --fail-with-body 'https://api.paypercut.io/v1/regulatory_disclosures' \
  -H "Authorization: Bearer $PAYPERCUT_SECRET_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d "{\"account\":\"$ACCOUNT_ID\",\"capability\":\"bg_nra_ecommerce\"}"

The initial response is typically 202 Accepted, with a Location header and a disclosure such as:

{
  "id": "regdisc_01JEXAMPLE0000000000000000",
  "object": "regulatory_disclosure",
  "account": "acct_example",
  "live_mode": false,
  "capability": "bg_nra_ecommerce",
  "form": "bg_nra_appendix_33",
  "form_version": "2020-07-31",
  "status": "pending",
  "created_at": "2026-10-28T09:00:00Z",
  "updated_at": "2026-10-28T09:00:00Z"
}

3. Wait for completion

Set DISCLOSURE_ID to the returned ID. This example uses jq, polls every two seconds for up to two minutes, and stops on a request error or terminal status:

export DISCLOSURE_ID='YOUR_DISCLOSURE_ID'
for attempt in $(seq 1 60); do
  response=$(curl --fail-with-body -sS \
    "https://api.paypercut.io/v1/regulatory_disclosures/$DISCLOSURE_ID" \
    -H "Authorization: Bearer $PAYPERCUT_SECRET_KEY" \
    -H "Paypercut-Account: $ACCOUNT_ID") || break
  status=$(printf '%s' "$response" | jq -r '.status')
  if [ "$status" = ready ] || [ "$status" = failed ]; then
    printf '%s\n' "$response" | jq .
    break
  fi
  sleep 2
done

A ready response can look like this illustrative example. The array contents and coverage depend on the account:

{
  "id": "regdisc_01JEXAMPLE0000000000000000",
  "object": "regulatory_disclosure",
  "account": "acct_example",
  "live_mode": false,
  "capability": "bg_nra_ecommerce",
  "form": "bg_nra_appendix_33",
  "form_version": "2020-07-31",
  "status": "ready",
  "created_at": "2026-10-28T09:00:00Z",
  "updated_at": "2026-10-28T09:00:05Z",
  "completed_at": "2026-10-28T09:00:05Z",
  "coverage": {
    "status": "incomplete",
    "scope": "paypercut_managed_payment_information",
    "issues": [{"code": "receiving_currency_support_unresolved"}]
  },
  "data": {"payment_arrangements": [{
    "merchant_identifier": {"value": "00123456"},
    "virtual_pos_identifier": {"value": "00001234"},
    "currency": "BGN",
    "payment_methods": ["card"],
    "receiving_accounts": []
  }]}
}

If the loop times out while the disclosure is still pending or generating, retain the ID and check again later. A ready disclosure may have incomplete coverage; inspect coverage.issues and all entries in data.payment_arrangements. See information and coverage. If it is failed, see lifecycle.

4. Download the document

Once the disclosure is ready, follow the document download instructions. To fetch a fresh snapshot after information changes, see fresh disclosures.

Overview

Disclosure lifecycle