Decide
POST /decide routes one payment. It evaluates the merchant’s active routing rule, ranks the result by success rate, cost and volume commitments, and answers with the connectors to try in order. /routing/hybrid exposes the same evaluation under a different request and response.
Authenticate with Authorization: Bearer <token> or x-api-key: <key>.
Merchant
The merchant is named by thex-connected-merchant-id header, never the request body.
x-request-id identifies the call. One is generated if absent, and it comes back as a response header. merchant_reference_id is your own reference for the payment and is echoed in the response.
Request
payment_id, amount, currency, routing_config.algorithm_for and routing_config.eligible_connectors. Other fields may be omitted or null, and unknown fields are rejected.
amountis an unsigned integer in minor units.- Country codes are ISO 3166 alpha-2.
billing_country, thenbusiness_country, supplies the country the decider scores on. - BINs are strings, so leading zeros are kept.
- A connector needs a nonempty
connector.merchant_connector_idis optional and, when sent, nonempty. A connector named without an account is matched and scored by its name alone. metadataadds custom rule parameters. It cannot overwrite a payment field or a configured rule key.payment_type(non_mandate,setup_mandate,ppt_mandateand so on) routes mandate payments, such as a processor-token charge to the processor holding the token. A rule that tests it matches only when it is sent, and it does not set the decider’s transaction type.authentication_typeis both matched by rules and scored by the decider.routing_config.decision_armnames the arm the caller assigned,controlorvariant. It is kept in the request audit and does not override Decision Engine’s own experiment assignment.routing_configalso carriespreferred_connectors,ranking_algorithm,elimination_enabledandenable_multi_objective, which the decider applies where the merchant’s feature and experiment gates allow it.
Rule keys
Most fields are matched under their own name, andmetadata entries under their own keys. These are matched under a different key, so write rules against the key rather than the field name.
Country codes are matched as the configured country names, which the adapter derives from the alpha-2 code. Other enum values match exactly where the configuration defines the value, otherwise case-insensitively.
Response
connectors is the order to try. The first is the choice and the rest the retry order. Every connector in the response, in every section, has the same {connector, merchant_connector_id} shape, and merchant_connector_id is null for a connector named without an account.
outcome says how the order was reached:
strategy names the layer that set the order (rule, success_rate, cost, volume_commitment, debit_network, candidate_order, none) and reason the specific case, for example rule_matched, success_rate_ranked, cost_optimized, no_active_rule, rule_output_not_eligible, rule_input_invalid, or success_rate_unavailable. New values may be added to these enums. message is for people reading logs, so branch on reason.
Each routing layer has a section, null when that layer did not run: rule (null when the rule layer failed), success_rate (null when the sr-routing setting is off or the A/B arm has no SR layer, with status: failed when the decider failed and the order fell back), cost, volume_steering, and debit_routing. success_rate.diagnostics carries the decider’s internals for support and is not covered by compatibility guarantees.
warnings lists problems the decision routed around: rule_input_invalid (a request value the routing configuration does not allow, where param names the request field such as card.card_network, and there is one warning per invalid value), rule_evaluation_failed (the rule could not be evaluated for another reason), rule_output_not_eligible and rule_output_partially_eligible (the rule chose connectors outside eligible_connectors), and success_rate_failed. Routing problems never fail the call.
id is unique per decision, so a retried payment’s decisions stay apart. Analytics record the request and response under the route name decide.
Feedback
Report the outcome withPOST /update-gateway-score, naming the connector as "connector:merchant_connector_id", or connector alone when it was named without an account.