Menu
Guides
API Reference

API Reference
Filter By
POST
GET
PUT
DELETE
PATCH

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 == and in with that field return false, while comparisons using != return true. 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

SummaryMethodPath
Create policy rulePOST/api/payment-configuration-service/policy-rules
List policy rulesGET/api/payment-configuration-service/policy-rules
Get policy rule by IDGET/api/payment-configuration-service/policy-rules/{id}
Update policy rulePUT/api/payment-configuration-service/policy-rules/{id}
Delete policy ruleDELETE/api/payment-configuration-service/policy-rules/{id}

Payment policy evaluation

SummaryMethodPath
Evaluate payment policiesPOST/api/pvt/payment-systems/search