Payment methods

Configuring what a checkout may offer on revenexx — method definitions with their restrictions and fees, the eligibility call, and the provider catalogue with its availability flag.

Two layers of configuration sit in front of a payment: a method is the line a checkout offers, and a provider is the PSP account behind it.

Base path: https://api.revenexx.com/v1/payments.

Methods

Request

curl -X POST https://api.revenexx.com/v1/payments/methods \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..." \
  -H "Content-Type: application/json" \
  -d '{
        "code": "invoice",
        "name": "Invoice",
        "kind": "self_managed",
        "countries": ["DE", "AT"],
        "min_order_value": 50,
        "fee_type": "fixed",
        "fee_amount": 2.5,
        "fee_currency": "EUR",
        "enabled": true
      }'

Field	Meaning
`code`	Required. The value every payment, every checkout and every ERP names this method by.
`name`, `labels`, `description`	Display.
`kind`	`self_managed` (invoice, prepayment) or `psp`.
`provider`, `provider_method`	Which PSP account and which of its methods. Only for `kind: "psp"`.
`countries`	Allow-list. Empty or null means unrestricted.
`min_order_value`, `max_order_value`	Amount bounds.
`fee_type`	`none`, `fixed` or `percent`, with `fee_amount` and `fee_currency`.
`enabled`	Defaults to `false` — a new method reaches no checkout until it is switched on.
`position`	The order a checkout prints them in.

Two defaults to know before the first call:

enabled is false. Creating a method changes nothing a buyer sees.
kind is self_managed. A card or wallet method needs kind: "psp" plus a provider the catalogue carries, or it falls back to the tenant's default_provider at payment time and fails there if none is set.

Choose code once. Once a single payment has been made under it, a rename is refused with 409.

A duplicate code in one tenant is a 409.

Ask what a buyer may pay with

Request

curl -X POST https://api.revenexx.com/v1/payments/methods/eligible \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..." \
  -H "X-Revenexx-Market: de" \
  -H "Content-Type: application/json" \
  -d '{"country":"DE","amount":249.90,"currency":"EUR"}'

The checkout's question — what can this buyer pay with? — answered server-side before any PSP is involved, so a storefront never renders a method the create would then refuse.

It reads only: nothing is written and no provider is called. Eligible methods come back sorted by position with their fee already computed for this amount, and fee_display says whether those fees are gross or net per the tenant's setting.

Everything else lands in excluded with the reason in words — "country FR not in [DE, AT]" — which is what makes a support question answerable. That is diagnostics, not something to show a buyer: it is how a merchant finds out why their invoice method is missing from a checkout.

Restriction dimensions are ANDed and entries within one are ORed; an empty dimension means unrestricted. A context matching nothing is 200 with an empty methods list, never 404.

Two things it does not check

It does not check whether the method's PSP is configured and enabled. A method whose provider is switched off is still offered here and fails at POST /v1/payments. (A provider a method names can no longer be deleted, which closes the other half of the same gap.)It knows nothing about the buyer beyond country and amount. No segment, no credit standing, no payment terms.

Eligibility is also enforced at POST /v1/payments — the same rules answer 422 there — so this route is an optimisation for the UI, not the guard.

Providers

Request

curl https://api.revenexx.com/v1/payments/providers/catalog \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..."

Call the catalogue first. It is the closed set of provider codes a configuration accepts — anything else is refused with 400 and a message listing these. It runs to roughly thirty connectors, is identical for every tenant, and changes only with a release of the app, so it is safe to cache hard.

Per entry:

Field	Meaning
`code`	The value a configuration takes as `provider`, and the `{slug}` the logo route serves.
`label`	The PSP's own name, for a picker.
`auth_type`	The scheme the connector authenticates with.
`credential_fields`	The key names to put inside `credentials` — never values, which come from the PSP's own dashboard. This is the list a credentials form renders.
`logo_url`	The logo that ships with the app.
`available`	Whether a driver for this provider exists in this deployment.

Three providers are listed but cannot transact

available: false means configurable but not usable. Such a provider can be created and stored, and every transaction through it fails with provider_unavailable. Grey it out in a picker rather than hiding it, so an operator can see it is coming.Three providers are in this state today:

Provider	Code
PAYONE	`payone`
Computop Paygate	`computop`
Unzer	`unzer`

Read available from the catalogue rather than hard-coding this list — it changes with a release.

Configuring an account

Request

curl -X POST https://api.revenexx.com/v1/payments/providers \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..." \
  -H "Content-Type: application/json" \
  -d '{
        "provider": "stripe",
        "name": "Stripe (live)",
        "test_mode": false,
        "enabled": true,
        "credentials": { "api_key": "…" }
      }'

PSP secrets are write-only.credentials and webhook_secret are accepted on create and update, stored for the drivers, and never returned by any route — responses carry the public columns only (id, provider, name, enabled, test_mode, options, timestamps). To rotate a secret, write the new value; there is no way to read the current one back.

Seeding a fresh shop

Request

curl -X POST https://api.revenexx.com/v1/payments/methods/defaults \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..." \
  -H "Content-Type: application/json" \
  -d '{}'

Writes the four methods a shop starts with — invoice and prepayment as self-managed, card and PayPal routed at the built-in mock PSP so a fresh install can complete a checkout end to end — plus the four provider rows behind them: the mock, Stripe, PayPal and Novalnet.

Stripe, PayPal and Novalnet arrive disabled, in test mode and without credentials; the mock arrives enabled, because it moves no money.

The app runs this itself on install, so calling the route is for the second time and after: a method someone deleted, or a row a later release added that an existing install never got. Re-running is safe by design — it never duplicates and never overwrites, so nothing an operator has set can be undone. Only genuinely missing option keys are filled, and those rows are reported as updated rather than created.

Where to go next

Payment lifecycle — creating and moving a payment.
Price lists — the amount a payment is for.
Orders — where payment_status is recorded.

Was this page helpful?