Payment Controls API
Payment controls are allow / deny rules evaluated against every incoming payment. A rule matches on one identifier type — a BIN range, a card fingerprint, an IP, a country, an ECI value, etc. — and either allows or denies matching payments.
Controls exist at two levels:
- Acquirer-level (
/v1/payment_controls/...): applied to every merchant under your acquirer. - Merchant-level (
/v1/acquirer/merchants/:merchant_id/payment_controls/...): applied to a single merchant.
Which level wins on conflict is governed by the merchant's
rule_precedence setting.
Identifier types
| Type | Identifier format |
|---|---|
bin_range | A BIN, or two comma-separated BINs forming a range. |
bin_country | ISO 3166-1 alpha-2 country of the issuing BIN. |
pan | Full card number. |
fingerprint | Card fingerprint as computed by the gateway. |
ip | IPv4 address of the customer device. |
ip_country | ISO 3166-1 alpha-2 country resolved from the customer IP. |
eci | ECI indicator (00, 01, 02, 05, 06, 07). |
tds_status | 3DS authentication status (Y, A, N, U, R). |
Required permissions: payment_controls_read,
payment_controls_create, payment_controls_update,
payment_controls_delete.
Authentication
- HTTP: Bearer Auth
Acquirer API key sent as a bearer token:
Authorization: Bearer acquirer_key_...
Keys are created from the Acquirer Dashboard and carry an explicit set of permissions. Every request is scoped to the acquirer that owns the key — resources of other acquirers are never visible. Keys may be IP-restricted; requests from non-whitelisted IPs are rejected with HTTP 401. See the Authentication page for details.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Bearer format: | acquirer_key_* |