Payment Policies API
The Payment Policies API allows VTEX merchants to configure rules that include or exclude payment systems for specific cart items. The Payment Configuration Service (PCS) stores policy rules, while the Payment Information Service (PIS) evaluates those rules during checkout and returns the payment systems available for each item.
This feature is in closed beta, meaning only specific customers can access it now. If you want to implement it in the future, please contact our Support.
Rule engine
Policy rule expressions use JSONLogic and are evaluated for each cart item separately. All active rules that match an item are applied. Rules are applied in ascending priority order, and the result is the same in any order: Exclude removes the listed payment systems, and Include keeps only the listed payment systems, but never restores a payment system removed by Exclude.
Context variables
| Variable | Type | Description |
|---|---|---|
collectionIds |
Array of integers | Collections that the item belongs to. An empty, null, or missing list produces the same result. |
seller |
String | Seller that fulfills the item. An empty or whitespace-only value is treated as not sent. |
shippingData.state |
String | Delivery state code, such as NY. An empty or whitespace-only value is treated as not sent. |
Variable names aren't validated when a rule is saved. Any other name is treated as a missing field: comparisons using
==andinwith that field returnfalse, while comparisons using!=returntrue. Logical operators combine these results normally.
Operators
| Operator | Usage rules |
|---|---|
and, or |
Every operand must be a condition (object). Literal values are rejected. |
in |
Requires two operands. Each operand is a value, a list, or {"var": "path"}. When the second operand is a list, the type and value must match: "139" isn't in [139]. |
== |
Requires two operands. Each operand is {"var": "path"}, a non-empty string other than "null", or an integer. Booleans, decimals, and lists are rejected. A number is equal to the string of the same number: "1" == 1 is true. |
!= |
Same rules as ==. Returns the opposite result. |
! |
Negates exactly one condition: {"!": {...}} or {"!": [{...}]}. Literal values and a standalone var are rejected. |
var |
Field path as a string. Use a dot to access nested fields, such as shippingData.state. Default values aren't supported. |
Any other operator is rejected with status 422. There's no not in operator; use {"!": {"in": [...]}} instead.
Each expression can have up to 500 operators. The and, or, !, in, ==, and != operators count toward this limit, and var doesn't.
When an item doesn't have a field used by a comparison, in and == return false, and != returns true. ! negates the result of its child condition, so negating a missing-field == or in comparison returns true, while negating a missing-field != comparison returns false. To prevent a negation from matching items without the field, require the field with and, as in {"and": [{"var": "seller"}, {"!": {...}}]}.
Error messages
Policy rule endpoints return errors in the Problem Details format, with the type, title, status, detail, and instance fields. The following tables list the detail values. Errors returned by the expression validator may include additional parameter information at the end of the message.
400 Bad Request
| When | detail |
|---|---|
The request body is missing expression, enabled, priority, or action. Messages for all missing fields are returned together. |
Expression is required. enabled is required. priority is required. action is required. |
action has a value other than Include or Exclude, including a different capitalization. |
action must be Include or Exclude. |
422 Unprocessable Content
| When | detail |
|---|---|
| The expression uses an unsupported operator. | Unsupported expression: JSONLogic operator "!==" is not supported. |
| An operator object has more than one key. | Unsupported expression: operator object must contain exactly one property, found "!=", "foo". |
==, !=, or in doesn't have exactly two operands. |
Unsupported expression: "!=" must have exactly two operands. |
! negates a literal value or a standalone var. |
Unsupported expression: "!" must negate exactly one condition, not a literal or a bare var. |
and or or has a literal value as an operand. |
Unsupported expression: every operand of "and" must be a condition, not a literal. |
== or != has a boolean or decimal operand. |
Unsupported expression: inside "==", each operand must be {"var":"path"}, a non-empty string other than "null", or an integer. |
==, !=, or in has null or "null" as an operand. |
Unsupported expression: null is not allowed as a literal inside "==", "!=" or "in", neither as JSON null nor as the string "null". |
==, !=, or in has an empty or whitespace-only string as an operand. |
Unsupported expression: an empty or whitespace string is not allowed as a literal inside "==", "!=" or "in". |
var has a default value. |
Unsupported expression: inside "in", {"var": ...} must be a single string path (default values are not supported). |
| The expression has more than 500 operators. | Expression exceeds maximum conditionals (500). Found: 501. |
priority is outside the 0 to 999 range. A blank name or an empty paymentSystems list also returns 422. |
Priority must be between 0 and 999. |
The search endpoint returns 400, 403, and 408 errors as plain text, not in the Problem Details format.
For more information and examples, see Using payment policies.
Endpoints
Payment policy rules
| Summary | Method | Path |
|---|---|---|
| Create policy rule | POST | /api/payment-configuration-service/policy-rules |
| List policy rules | GET | /api/payment-configuration-service/policy-rules |
| Get policy rule by ID | GET | /api/payment-configuration-service/policy-rules/{id} |
| Update policy rule | PUT | /api/payment-configuration-service/policy-rules/{id} |
| Delete policy rule | DELETE | /api/payment-configuration-service/policy-rules/{id} |
Payment policy evaluation
| Summary | Method | Path |
|---|---|---|
| Evaluate payment policies | POST | /api/pvt/payment-systems/search |