> ## Documentation Index
> Fetch the complete documentation index at: https://yuno-3979e326-2026-05-13-universal-sdk-proposal.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Routing

> Creates a routing for one (account_code, payment_method) pair. Always live on success.

Creates a routing for one `(account_code, payment_method)` pair. Each routing references **connections** by their `connection_id`. Make sure your connections are created and `ACTIVE` for the requested `payment_method` *before* you call routing.

### Body

<ParamField body="payment_method" type="enum" required>
  E.g., `CARD`, `PIX`, `WALLET`. Immutable per routing — to route a different method, create a new routing.
</ParamField>

<ParamField body="name" type="string" required>
  Free-form label.
</ParamField>

<ParamField body="default_route" type="object" required>
  The route used when no `condition_sets[]` matches.

  <Expandable title="properties">
    <ParamField body="steps" type="object[]" required>
      Each step is one provider attempt. `index` values are contiguous starting at 1.

      <Expandable title="item">
        <ParamField body="index" type="integer" required>
          Step ordinal.
        </ParamField>

        <ParamField body="provider_id" type="string" required>
          Must match the provider of the connection.
        </ParamField>

        <ParamField body="connection_id" type="UUID" required>
          Must be `ACTIVE` and support the `payment_method`.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="condition_sets" type="object[]">
  Optional. Ordered by `sort_number` — first matching set wins.

  <Expandable title="item">
    <ParamField body="sort_number" type="integer" required>
      Priority of the condition set.
    </ParamField>

    <ParamField body="name" type="string" required>
      Label for the set.
    </ParamField>

    <ParamField body="conditions" type="object[]" required>
      List of [Conditions](/reference/organizations/routing/routing-conditions) that must match.
    </ParamField>

    <ParamField body="route" type="object" required>
      The steps to execute if this set matches.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="id" type="string">
  Unique identifier for the routing.
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
       --url https://api.y.uno/v1/routing \
       --header 'Content-Type: application/json' \
       --header 'X-Idempotency-Key: <UUID>' \
       --header 'private-secret-key: <YOUR_SECRET_KEY>' \
       --header 'public-api-key: <YOUR_PUBLIC_KEY>' \
       --data '
  {
    "payment_method": "CARD",
    "name": "Card routing",
    "default_route": {
      "steps": [
        {
          "index": 1,
          "provider_id": "STRIPE",
          "connection_id": "f1a3c4d5-7b8e-4a2c-9d1e-3f4a5b6c7d8e"
        }
      ]
    }
  }
  '
  ```

  ```json Response Example theme={null}
  {
    "id": "r_8f2c1d3e-4b5a-6c7d-8e9f-0a1b2c3d4e5f",
    "account_code": "acc-uuid",
    "payment_method": "CARD",
    "name": "Card routing",
    "default_route": {
      "steps": [
        { "index": 1, "provider_id": "STRIPE", "connection_id": "f1a3c4d5-..." }
      ]
    },
    "created_at": "2026-05-12T14:30:00Z",
    "updated_at": "2026-05-12T14:30:00Z"
  }
  ```
</CodeGroup>

### Errors

| HTTP  | `code`                           | When                                                                                                    |
| ----- | -------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `400` | `ROUTING_VALIDATION_FAILED`      | Schema or rule violation. `details` names the offending field/path.                                     |
| `400` | `ROUTING_PROVIDER_NOT_AVAILABLE` | A step references a `(provider_id, connection_id)` not active for the account on this `payment_method`. |
| `409` | `ROUTING_ALREADY_EXISTS`         | A routing already exists for this `(account, payment_method)`. Use `PATCH` to update it.                |
| `403` | `INSUFFICIENT_SCOPE`             | API key missing `routing:write`.                                                                        |


## OpenAPI

````yaml openapi/organizations/routing/create-routing.json POST /routing
openapi: 3.1.0
info:
  title: Routing API - Create
  version: 1.0.0
servers:
  - url: https://api-sandbox.y.uno/v1
security:
  - sec0: []
    sec1: []
paths:
  /routing:
    post:
      summary: Create a Routing
      description: Creates a routing for one (account_code, payment_method) pair.
      operationId: create-routing
      parameters:
        - name: X-Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - payment_method
                - name
                - default_route
              properties:
                payment_method:
                  type: string
                  example: CARD
                name:
                  type: string
                  example: Card routing
                default_route:
                  type: object
                  required:
                    - steps
                  properties:
                    steps:
                      type: array
                      items:
                        type: object
                        required:
                          - index
                          - provider_id
                          - connection_id
                        properties:
                          index:
                            type: integer
                            example: 1
                          provider_id:
                            type: string
                            example: STRIPE
                          connection_id:
                            type: string
                            format: uuid
                            example: f1a3c4d5-7b8e-4a2c-9d1e-3f4a5b6c7d8e
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  account_code:
                    type: string
                  payment_method:
                    type: string
                  name:
                    type: string
                  default_route:
                    type: object
                  created_at:
                    type: string
                    format: date-time
                  updated_at:
                    type: string
                    format: date-time
components:
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: PUBLIC-API-KEY
      x-default: <Your PUBLIC-API-KEY>
    sec1:
      type: apiKey
      in: header
      name: PRIVATE-SECRET-KEY
      x-default: <Your PRIVATE-SECRET-KEY>

````