# Find the route executions of a Payment

`GET /v2/payments/{id}/route-executions`

Core API v2, Payments.

Retrieve a paginated list of the Route executions of a Payment: one for each time the Payment was sent for authorization through a Route, whatever the result, oldest first unless you sort otherwise. Each one names the Route version that ran and lists every step it took: the branches that matched or did not, the nodes it skipped and why, and the gateway attempts it made, in order.

**Authentication:** Send `Authorization: Bearer <token>`. To authenticate, generate a Secret API Key from your ODUS Dashboard and include it in the `Authorization` header as follows: `Authorization: Bearer <YOUR_SECRET_API_KEY>`

## Parameters

### Path parameters

- `id` (string, required)

### Query parameters

- `id` (filter): Send as `id[<operator>]=<value>`. Operators: `eq`, `ne`, `in`, `nin`.
- `status` (filter): Send as `status[<operator>]=<value>`. Operators: `eq`, `ne`, `in`, `nin`.
- `outcome` (filter): Send as `outcome[<operator>]=<value>`. Operators: `eq`, `ne`, `in`, `nin`.
- `createdAt` (filter): Send as `createdAt[<operator>]=<value>`. Operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`.
- `sortDirection` (string): Sort direction. Defaults to ASC. One of `ASC`, `DESC`, `asc`, `desc`.
- `sortBy` (string): Field to sort by. Defaults to createdAt. One of `id`, `createdAt`.
- `limit` (number): Number of items per page. Defaults to 10, capped at 100. Send 0 to return no items, which is how you ask for "withTotal"'s count without fetching a page you do not need.
- `cursor` (string): Opaque cursor from a previous response ("nextCursor" or "prevCursor"). Send it back with the same "sortBy" and "sortDirection" — the cursor encodes them and a request that disagrees is rejected. "limit" may change between pages and simply changes the page size. Omit "cursor" for the first page.
- `withTotal` (boolean): Set to true to also return how many items match the filters, as "totalCount" in the response's pagination. The count ignores "cursor", so it does not change as you page — fetch it once per set of filters rather than on every page. Counting stops at 10000, above which "totalCountIsExact" is false. Omit this parameter to skip the count entirely.

## Responses

### `200`

OK

Type: object.

- `pagination` (object (CursorPageMetaDTO))
  - `mode` (string, required): Discriminator identifying cursor-based pagination metadata. One of `cursor`. Default `cursor`. Example: `cursor`.
  - `pageSize` (number, required): Number of items per page. Minimum 0. Example: `10`.
  - `hasNextPage` (boolean, required): Whether a next page exists. Example: `false`.
  - `hasPreviousPage` (boolean, required): Whether a previous page exists. Example: `true`.
  - `nextCursor` (string, required, nullable): Opaque cursor for fetching the next page. Null when there is no next page. Example: `eyJzIjoiY3JlYXRlZEF0IiwiZCI6ImFzYyIsIm4iOiJmb3J3YXJkIn0`.
  - `prevCursor` (string, required, nullable): Opaque cursor for fetching the previous page. Null when there is no previous page. Example: `eyJzIjoiY3JlYXRlZEF0IiwiZCI6ImFzYyIsIm4iOiJiYWNrd2FyZCJ9`.
  - `totalCount` (number): Number of items matching this request's filters, ignoring the cursor. Present only when the request sets "withTotal". Counting stops at 10000; read "totalCountIsExact" before showing this as a total. Example: `139`.
  - `totalCountIsExact` (boolean): Whether "totalCount" is the exact number of matching items. False when more items match than counting reaches, in which case "totalCount" holds that limit and should be shown as a lower bound, for example "over 10,000". Present only when the request sets "withTotal". Example: `true`.
- `data` (array of object (RouteExecutionDTO))
  - `createdAt` (string (date-time), required): The date and time when the entity was created. Example: `2024-02-18T12:00:00Z`.
  - `updatedAt` (string (date-time), required, nullable): The date and time when the entity was last updated. Example: `2024-02-21T12:15:00Z`.
  - `metadata` (map of string to string, nullable): Metadata used by merchants to store additional information about the entity.
  - `id` (string, required): The unique identifier of the route execution. Example: `rtx_2mXGTxXIkqv4uSdbm8DJCzvHUIu`.
  - `payment` (string, required): The ID of the payment the route was run for. Example: `pay_2mXGTxXIkqv4uSdbm8DJCzvHUIu`.
  - `routeVersion` (object, required): The route version that ran. Activating another version later does not change it.
    - `createdAt` (string (date-time), required): The date and time when the entity was created. Example: `2024-02-18T12:00:00Z`.
    - `updatedAt` (string (date-time), required, nullable): The date and time when the entity was last updated. Example: `2024-02-21T12:15:00Z`.
    - `metadata` (map of string to string, nullable): Metadata used by merchants to store additional information about the entity.
    - `id` (string, required): The unique identifier of the route version. Example: `rtv_2mXGTxXIkqv4uSdbm8DJCzvHUIu`.
    - `route` (string, required): The ID of the route this is a version of. Example: `rte_2mXGTxXIkqv4uSdbm8DJCzvHUIu`.
    - `number` (integer, required): The version's number. A route's first version is 1, and each version published after it counts up by one. Minimum -9007199254740991. Maximum 9007199254740991. Example: `2`.
  - `status` (string, required): `processing` while the route is still choosing or trying gateways, `completed` once it has finished, and `failed` if it stopped on an error before finishing. One of `processing`, `completed`, `failed`. Example: `completed`.
  - `outcome` (string, required, nullable): How the route ended. `null` while it is `processing`, and when it `failed` before deciding. `not_routed` means no gateway was attempted. One of `authorized`, `pending`, `declined`, `unknown`, `not_routed`. Example: `authorized`.
  - `facts` (object, required): What the route's conditions were evaluated against. They are fixed when the execution starts.
    - `amount` (integer, required): The amount of the payment, in minor units. Minimum -9007199254740991. Maximum 9007199254740991. Example: `1000`.
    - `currency` (string, required): The currency of the payment. One of `usd`, `eur`, `gbp`, `cad`, `aud`, `pln`, `czk`, `sek`, `dkk`. Example: `usd`.
    - `initiator` (string, required): Who initiated the payment: `customer` or `merchant` Example: `customer`.
    - `card` (object, required, nullable): What was known about the card. A condition on a card field that was `null` here had nothing to compare, so it did not match.
      - `brand` (string, required, nullable): The brand of the card, or `null` when it was not known. Example: `visa`.
      - `bin` (string, required, nullable): The card BIN/IIN (Bank/Issuer Identification Number) Example: `41472000`.
      - `issuerName` (string, required, nullable): The name of the bank that issued the card, or `null` when it was not known when the payment was routed. Example: `Capital One`.
      - `issuerCountry` (string, required, nullable): The country of the bank that issued the card, as an ISO 3166-1 alpha-2 code, or `null` when it was not known. Example: `US`.
      - `fundingType` (string, required, nullable): How the card is funded: `credit`, `debit`, `prepaid` or `charge`, or `null` when it was not known. Example: `credit`.
    - `metadata` (map of string to string, required, nullable): The payment's metadata values that the route's conditions name, or `null` when they name none. Other metadata is not kept.
    - `statementDescriptor` (string, required, nullable): The payment's statement descriptor, or `null` when it had none. A condition on `statementDescriptor` did not match a payment without one. Example: `Some product`.
    - `statementDescriptorSuffix` (string, required, nullable): The payment's statement descriptor suffix, or `null` when it had none. A condition on `statementDescriptorSuffix` did not match a payment without one. Example: `PRO PLAN`.
  - `steps` (array of object, required): Every node the route reached, in the order it reached them, with what it decided there. The gateway attempts are the `attempted` steps, in `attempt` order.
    - `id` (string, required): The unique identifier of the step. Example: `rtxs_2mXGTxXIkqv4uSdbm8DJCzvHUIu`.
    - `position` (integer, required): The place of the step in the order the route reached its nodes, from 0. Minimum -9007199254740991. Maximum 9007199254740991. Example: `0`.
    - `route` (string, required): The ID of the route the node belongs to. It differs from the version's route when a `route` node led into another route. Example: `rte_2mXGTxXIkqv4uSdbm8DJCzvHUIu`.
    - `path` (string, required): Where the node sits in that route's decision tree. Example: `$.branches[0].then.children[1]`.
    - `result` (string, required): What happened at the node. `matched`: a condition took the branch in `branch`, or a split took the output in `branch`. `no_match`: the branch in `branch` did not match. `unknown_fact`: the branch could not be decided because the payment lacked the facts in `unknownFields`, so it did not match. `skipped`: the node was passed over for the `reason` given. `attempted`: the payment was sent to `gatewayProfile`. `withheld`: the route stopped before trying `gatewayProfile`, for the `reason` given. One of `matched`, `no_match`, `unknown_fact`, `skipped`, `attempted`, `withheld`. Example: `matched`.
    - `branch` (string, required, nullable): For a condition, the index of the branch, counted from 0, or `else`. For a split, the index of the output the payment took, counted from 0. `null` for other nodes. Example: `0`.
    - `reason` (string, required, nullable): Why a node was `skipped` or `withheld`; `null` otherwise. New reasons may be added: branch on `result`, and treat a reason you do not recognise as an explanation only. Skipped: `gateway_not_found`, `gateway_inactive`, `gateway_already_attempted`, `passed_over` (an earlier attempt had already moved past the node), `route_not_found`, `route_depth_exceeded`, `no_branch_matched`, `pool_max_attempts`, `attempt_cap`, `evaluation_limit`, `unsupported_node`. Withheld: `unknown_outcome` (the previous attempt got no answer and may have charged the card), `deadline` (too little time was left in the request for another attempt). Example: `gateway_inactive`.
    - `gatewayProfile` (string, required, nullable): The ID of the gateway profile the node names, or `null` for a node that names none. Example: `gwp_2mXGTxXIkqv4uSdbm8DJCzvHUIu`.
    - `transaction` (string, required, nullable): For an `attempted` step, the ID of the transaction the attempt created; `null` otherwise, and until the attempt is answered. Example: `tx_2mXGTxXIkqv4uSdbm8DJCzvHUIu`.
    - `attempt` (integer, required, nullable): For an `attempted` step, which attempt of the execution it was, counted from 1; `null` otherwise. Minimum -9007199254740991. Maximum 9007199254740991. Example: `1`.
    - `outcome` (string, required, nullable): For an `attempted` step, what the gateway answered: `authorized`, `declined`, `pending` (waiting on the customer or the gateway, such as 3D Secure) or `unknown` (no answer, so the card may have been charged). `null` otherwise, and while the attempt is in progress. Example: `declined`.
    - `unknownFields` (array of string, required, nullable): For an `unknown_fact` step, the fields the condition needed that the payment did not have; `null` otherwise.
    - `unsupportedTerms` (array of string, required, nullable): For an `unknown_fact` step, the parts of the condition that could not be evaluated, as `<field> <operator>`; `null` when there were none.
    - `remainingBudgetMs` (number, required, nullable): For a step withheld for `deadline`, the time left in the request, in milliseconds; `null` otherwise. Example: `1200`.
    - `targetRoute` (string, required, nullable): For a skipped `route` node, the ID of the route it names; `null` otherwise. Example: `rte_2mXGTxXIkqv4uSdbm8DJCzvHUIu`.
    - `reachedAt` (string (date-time), required): When the route first reached the node. Example: `2024-02-18T12:00:00Z`.
    - `answeredAt` (string (date-time), required, nullable): For an `attempted` step, when the gateway answered; `null` otherwise, and while the attempt is in progress. Example: `2024-02-18T12:00:02Z`.

### `202`

The merchant is entitled but its environment is not provisioned yet. Provisioning has been kicked off (exactly once) and is in progress; retry the request — it succeeds once the environment is ready. Returned only for identity-token (dashboard) requests bound to a merchant, not for secret-key API calls; any such endpoint can return it while provisioning is underway.

Type: object (ProvisioningInProgress).

- `status` (string, required): Signals the merchant environment is still being provisioned. One of `provisioning`.
- `merchantAccountId` (string, required): The merchant account whose environment is being provisioned. Example: `dAI3aa87ROOeupeBCjNSKCOBOisBCYjB`.

### Errors

- `400`: The request was rejected. `type` is `invalid_request_error` when the request itself is at fault — `errors` then lists every problem found, with field-attributable entries prefixed by the field’s path; or `invalid_state_error` when the request was well-formed but the resource is not in a state that allows it.
- `401`: No API key was supplied, or the key is not valid. `type` is `authentication_error`.
- `403`: The API key is valid but lacks the permission this operation requires. `type` is `permission_error`.
- `404`: No resource exists with the requested identifier. `type` is `not_found_error`.
- `429`: Too many requests. A limit applies per operation; requests to other operations are unaffected. `type` is `rate_limit_error`. Use the `Retry-After-global` header to know when to retry.
- `500`: The request could not be completed because of an unexpected error. `type` is `api_error`.
- `503`: The request could not be served right now: the API is temporarily at capacity, or a dependency needed to authorize the request is unavailable — the auth service that verifies credentials, or the entitlement lookup behind it. `type` is `api_error`. It is raised before the operation runs, so the request had no effect, and unlike a plain 500 the condition is transient: retry with backoff.
- `504`: The request exceeded the processing time limit and was abandoned. `type` is `api_error` and `code` is `timeout` — unlike a plain 500 the request may still have taken effect, so retry with the same idempotency key rather than blindly.

Every error response has the same body: see [Errors](https://docs.odus.com/docs/guides/api-features/errors.md).

---

Generated from the Core API v2 OpenAPI document, https://api.odus.com/openapi.v2.json. Interactive page: https://docs.odus.com/docs/api/core/v2/payment-controller-find-all-route-executions-paginated