Admin payment forms

CRUD for manual payment forms — the guided instructions (Pago Móvil, Binance, bank transfer, Zelle, …) customers follow to pay. Paths are relative to the /api/v1 prefix; these are back-office endpoints requiring a super-admin token.

Requires a super-admin bearer token (see Admin auth). Super-admin only.

See Common errors.

Endpoints

Method URI Access Description
GET /admin/payment-forms Super admin List all payment forms
POST /admin/payment-forms Super admin Create a payment form
PATCH /admin/payment-forms/{paymentFormId} Super admin Update a payment form
DELETE /admin/payment-forms/{paymentFormId} Super admin Delete a payment form

The payment form object

index, store, and update present each form the same way:

{
  "id": 1,
  "name": "Pago Móvil",
  "internal_name": "bancamiga_pm",
  "category": "pago_movil",
  "internal_type": "PAYMENT_FORM",
  "currency": "VES",
  "auto_verify": true,
  "aguita_prc": 2.5,
  "commission_tiers": [
    { "min_amount": 0, "max_amount": 25, "aguita_prc": 2 }
  ],
  "tax_prc": 0,
  "tax_flat_cents": 0,
  "icon": "pago-movil",
  "active": true,
  "sort_order": 1,
  "schema": [
    { "type": "text", "index": 0, "label": "Banco", "content": "Bancamiga 0172" },
    { "type": "input", "index": 1, "label": "Referencia", "required": true, "input_type": "numeric", "key": true }
  ]
}

GET /admin/payment-forms

Lists all payment forms, ordered by sort_order then name. Not paginated.

Response 200

{ "items": [ { "id": 1, "name": "Pago Móvil", "active": true, "sort_order": 1 } ] }

POST /admin/payment-forms

Creates a payment form. The schema describes the form fields rendered to the customer.

Request body

Field Type Required Rules
name string yes ≤ 120 chars
internal_name string yes ≤ 80 chars, ^[a-z0-9_]+$, unique among payment forms
category string yes pago_movil, binance, bank_transfer, zelle, or other
currency string yes USD, VES, or USDT
auto_verify boolean no Defaults to false. When true on a pago_movil form, enables automatic verification; ignored for other categories
aguita_prc number yes 0–50 (commission %)
commission_tiers array|null no optional commission tiers over the order amount (USD); null/omitted uses the flat aguita_prc
commission_tiers[].min_amount number yes (per item) ≥ 0
commission_tiers[].max_amount number|null yes (per item) ≥ 0 and > min_amount; null = open-ended
commission_tiers[].aguita_prc number yes (per item) 0–50
tax_prc number no 0–50
tax_flat_cents integer no ≥ 0
icon string no ≤ 60 chars, nullable
active boolean no —
sort_order integer no ≥ 0
schema array yes ≥ 1 item (see below)

schema.* items

Field Type Required Rules
type string yes text or input
index integer yes ≥ 0
label string yes ≤ 200 chars
content string no ≤ 2000 chars, nullable
required boolean no —
hint string no ≤ 120 chars, nullable
regex string no ≤ 200 chars, nullable
input_type string no text or numeric
key boolean no —

commission_tiers tiers must not overlap; any amount not covered by a tier falls back to the flat aguita_prc. Invalid or overlapping tiers return a 422 ValidationError on the commission_tiers field.

Response 201 — { "form": { … } } (see the payment form object).

PATCH /admin/payment-forms/{paymentFormId}

Updates a payment form. All fields are optional; when schema is provided, each item's type, index, and label are required. Disabling the last active method is blocked.

Request body — same fields and rules as create, all optional (internal_name uniqueness ignores the current record).

Response 200 — { "form": { … } }.

Errors

Status Body When
404 { "error": "PaymentFormNotFound" } No payment form with that id
422 { "error": "AtLeastOneMethodRequired", "message": "…" } Setting active=false on the last active method

DELETE /admin/payment-forms/{paymentFormId}

Deletes a payment form. Deleting the last active method is blocked.

Response 200

{ "ok": true }

Errors

Status Body When
404 { "error": "PaymentFormNotFound" } No payment form with that id
422 { "error": "AtLeastOneMethodRequired", "message": "…" } Deleting the last active method