Skip to main content
By default a payment can use anything your project routes for the payer’s country and currency. A restriction narrows that set for one payment only, without touching your routing rules. Declare it at creation, on either surface:
It cannot be changed afterwards. A payment is created with the restriction it will keep.

​
Shape

Two independent axes, each with an allow and a deny list:
payment_methods names individual method codes — the same codes the methods endpoint returns. payment_method_categories names families, and a family covers every method inside it, including ones added to the catalogue later. On a hosted checkout, these keys sit alongside country_code and phone in the same restriction object and are independent of them.

​
How it resolves

  1. A denied value wins, on either axis. Nothing overrides a deny.
  2. With no allow list on either axis, everything that is not denied stays usable.
  3. Otherwise the method must appear on one of the two allow lists — the axes are a union, not an intersection.
So payment_methods.allow: ["card"] together with payment_method_categories.allow: ["mobile_money"] offers cards and all mobile money, not their overlap. Rule 1 means a contradiction resolves to a refusal: allowing momo_mtn while denying the mobile_money category leaves MTN unusable. That case is caught at creation rather than at payment time — see Rejected at creation.

​
Refusing one thing

The common case is excluding a family. Deny the category, not the code:
Denying the card code would only exclude one of the card methods; card_cb and card_kr would still be offered wherever they are routed. The category covers all three.
Digital wallets are their own category. Apple Pay, Google Pay, Link and Cash App are wallet, not card, even though a card funds them. Denying card does not stop a card-funded wallet payment.Note that wallet also holds Wave, Djamo and other account-based wallets that have nothing to do with cards. If you need “no card anywhere”, an allow list is more honest than stacking denies:

​
Categories

Do not hard-code the membership of a category. It is the catalogue’s business, and it grows.

​
What it affects

A restriction is applied everywhere a method could be chosen, not only at the point of payment: The last row is the one that matters for correctness. The catalogues are a convenience; the attempt check is the guarantee. A stale page or a hand-written request cannot get around it.

​
Rejected at creation

A restriction your project cannot honour is refused with 422 and no payment is created:
That covers the two ways of getting it wrong: restricting to a method you have not routed, and contradicting yourself across the two axes. Both would otherwise surface as an empty checkout in front of a payer. Listing the same value in allow and deny on the same axis is a validation error rather than a silent resolution:
Satisfiability is checked against your whole routing configuration, not against one country. allow: ["card"] passes creation if cards are routed anywhere in your project — a payer landing in a country where they are not routed still sees nothing. Restrict by category rather than by code when the payer’s country is not known upfront.

​
Reading it back

The restriction is echoed on the payment, and on the checkout when you used one. Only the keys you set are present:
On a hosted checkout, checkout.restriction carries the method lists next to the country and the obfuscated phone number.