Sample API — v1

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

  1. 01

    Call /v1/routing/decide before you authorise a payment.

  2. 02

    Send the payment to the first route in the ranked list.

  3. 03

    Report the result to /v1/routing/outcomes so the AI keeps learning.

Endpoints

POST/v1/routing/decide

Get a ranked list of routes for a payment.

FieldTypeDescription
customer_id*stringYour stable customer identifier.
amount*integerAmount in minor units (e.g. 4999 = 49.99).
currency*stringISO 4217 code, e.g. EUR.
card_binstringFirst 6–8 digits of the card.
routesstring[]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/outcomes

Report what happened to a routed payment.

FieldTypeDescription
decision_id*stringID returned by /decide.
route_id*stringRoute actually used.
status*enumapproved | declined | error
decline_codestringIssuer 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.

FieldTypeDescription
id*stringCustomer 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

CodeHTTPMeaning
RTE_NO_ROUTE422No configured route supports this currency or card.
RTE_UNKNOWN_DECISION404decision_id not found or older than 30 days.
RTE_DUPLICATE_OUTCOME409An 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 }
}