Personalized Routing API
Ask the AI where to send each payment. Guardyen ranks your acquirers and payment methods per customer based on their past successful transactions, then learns from every outcome you report.
Quick start
- 01
Call /v1/routing/decide before you authorise a payment.
- 02
Send the payment to the first route in the ranked list.
- 03
Report the result to /v1/routing/outcomes so the AI keeps learning.
Endpoints
POST
/v1/routing/decideGet a ranked list of routes for a payment.
| Field | Type | Description |
|---|---|---|
| customer_id* | string | Your stable customer identifier. |
| amount* | integer | Amount in minor units (e.g. 4999 = 49.99). |
| currency* | string | ISO 4217 code, e.g. EUR. |
| card_bin | string | First 6–8 digits of the card. |
| routes | string[] | Limit to these route IDs. Defaults to all configured. |
Request
curl -X POST https://api.guardyen.com/v1/routing/decide \
-H "Authorization: Bearer gy_test_sk_..." \
-H "Content-Type: application/json" \
-d '{"customer_id":"cus_8812","amount":4999,"currency":"EUR","card_bin":"424242"}'Response 200
{
"decision_id": "rd_01HF3K9Q",
"routes": [
{ "route_id": "acq_a", "success_probability": 0.97, "reason": "92% historical success" },
{ "route_id": "acq_b", "success_probability": 0.81 },
{ "route_id": "apm_local", "success_probability": 0.64 }
],
"model_version": "rte-2026.10",
"latency_ms": 31
}POST
/v1/routing/outcomesReport what happened to a routed payment.
| Field | Type | Description |
|---|---|---|
| decision_id* | string | ID returned by /decide. |
| route_id* | string | Route actually used. |
| status* | enum | approved | declined | error |
| decline_code | string | Issuer or acquirer decline code. |
Request
curl -X POST https://api.guardyen.com/v1/routing/outcomes \
-H "Authorization: Bearer gy_test_sk_..." \
-H "Content-Type: application/json" \
-d '{"decision_id":"rd_01HF3K9Q","route_id":"acq_a","status":"approved"}'Response 200
{ "received": true }GET
/v1/routing/customers/{id}See a customer's routing profile.
| Field | Type | Description |
|---|---|---|
| id* | string | Customer identifier (path). |
Request
curl -X GET https://api.guardyen.com/v1/routing/customers/cus_8812 \
-H "Authorization: Bearer gy_test_sk_..." \
-H "Content-Type: application/json"Response 200
{
"customer_id": "cus_8812",
"transactions": 128,
"preferred_route": "acq_a",
"success_rate": { "acq_a": 0.92, "acq_b": 0.71 }
}Error codes
| Code | HTTP | Meaning |
|---|---|---|
| RTE_NO_ROUTE | 422 | No configured route supports this currency or card. |
| RTE_UNKNOWN_DECISION | 404 | decision_id not found or older than 30 days. |
| RTE_DUPLICATE_OUTCOME | 409 | An outcome was already reported for this decision. |
Webhook
Event routing.model.updated is sent to your webhook endpoint.
Payload
{
"type": "routing.model.updated",
"data": { "model_version": "rte-2026.11", "uplift_estimate": 0.034 }
}