> ## Documentation Index
> Fetch the complete documentation index at: https://rain-sandbox-trial.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a payment route

> Creates a payment route that automatically processes incoming funds. Payment routes can route funds from fiat to on-chain or from on-chain to fiat.

> **Deprecation Notice:** This endpoint was previously named `/v1/automations`. The old path remains available as a deprecated alias. Update your integrations to use `/v1/payment-routes`.



## OpenAPI

````yaml /openapi.json post /payment-routes
openapi: 3.0.3
info:
  title: Issuing API
  description: This is the specification for Rain's Issuing API.
  termsOfService: https://www.rain.xyz/legal/authorized-user-terms
  contact:
    email: support@rain.xyz
  version: 1.3.0
servers:
  - url: https://api-dev.rain.xyz/v1
    description: Sandbox server
  - url: https://api.rain.xyz/v1
    description: Production server
security: []
tags:
  - name: paymentRoutes
    description: >-
      **Endpoint Migration:** The `/v1/automations` endpoints have been renamed
      to `/v1/payment-routes`. The old `/v1/automations` paths remain available
      as deprecated aliases during migration. Update your integrations to use
      `/v1/payment-routes` as the deprecated endpoints will be removed in a
      future release.
  - name: simulate
    description: >-
      Transaction simulation endpoints for testing integration flows in
      non-production environments. These endpoints let you trigger transaction
      events programmatically to automate integration tests and verify webhook
      handling without depending on external systems or staging real deposits.
      **Sandbox only** — all simulation endpoints return `404 Not Found` in
      production.
  - name: raindrops
    description: >-
      Rewards and points management endpoints. Custom API keys need
      `raindrops:read`/`raindrops:write` for general rewards endpoints and
      `raindrops-travel:read`/`raindrops-travel:write` for travel redemption
      endpoints.
    x-group: rewards
paths:
  /payment-routes:
    post:
      tags:
        - paymentRoutes
      summary: Create a payment route
      description: >-
        Creates a payment route that automatically processes incoming funds.
        Payment routes can route funds from fiat to on-chain or from on-chain to
        fiat.


        > **Deprecation Notice:** This endpoint was previously named
        `/v1/automations`. The old path remains available as a deprecated alias.
        Update your integrations to use `/v1/payment-routes`.
      operationId: createAutomation
      requestBody:
        description: Payment route configuration
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAutomationBody'
            examples:
              default:
                $ref: '#/components/examples/CreateAutomationRequestExample'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRoute'
              examples:
                default:
                  $ref: '#/components/examples/AutomationExample'
        '400':
          description: >-
            Invalid request - duplicate payment route or invalid
            source/destination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 400
                error: BadRequestError
                message: >-
                  Invalid request - duplicate automation or invalid
                  source/destination
        '401':
          description: Invalid authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 401
                error: Unauthorized
                message: Invalid or missing API key
        '403':
          description: Forbidden - team has not completed KYC verification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 403
                error: ForbiddenError
                message: Team has not completed KYC verification
        '404':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 404
                error: NotFoundError
                message: Bad Request
        '422':
          description: >-
            Unprocessable Entity - user or company has incomplete compliance
            data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 422
                error: UnprocessableEntityError
                message: User is missing required name information
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 500
                error: InternalServerError
                message: Internal server error
        '503':
          description: Service Unavailable - unable to verify compliance status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 503
                error: ServiceUnavailableError
                message: Unable to verify compliance status
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreateAutomationBody:
      type: object
      required:
        - source
        - destination
      properties:
        userId:
          type: string
          format: uuid
          description: User ID (for individual teams; provide either userId or companyId)
        companyId:
          type: string
          format: uuid
          description: Company ID (for company teams; provide either userId or companyId)
        source:
          $ref: '#/components/schemas/AutomationSource'
        destination:
          $ref: '#/components/schemas/AutomationDestination'
        refundAddress:
          type: string
          description: >-
            The address to refund funds to. Required when `source` is a crypto
            rail.
          pattern: >-
            ^(0x[a-fA-F0-9]{40}|T[1-9A-HJ-NP-Za-km-z]{31,43}|[1-9A-HJ-NP-Za-km-z]{32,44}|[GC][A-Z2-7]{55}|M[A-Z2-7]{68})$
        senderFees:
          type: array
          description: >-
            Optional array of sender fee configurations. Each fee is applied to
            transfers processed by this automation. Requires sender fees to be
            enabled for your account.
          items:
            type: object
            required:
              - type
              - amount
            properties:
              type:
                type: string
                enum:
                  - flat
                  - variable
                description: >-
                  The type of fee. `flat` is a fixed amount in the source
                  currency. `variable` is a percentage of the source amount.
              amount:
                type: string
                description: >-
                  The fee amount. For `flat` fees, this is the amount in the
                  source currency (e.g., `1.00` for $1.00). For `variable` fees,
                  this is a percentage (e.g., `2.5` for 2.5%).
        developerFees:
          type: array
          deprecated: true
          description: >-
            Deprecated: use `senderFees` instead. Still accepted for backward
            compatibility. If both are provided, `senderFees` takes precedence.
          items:
            type: object
            required:
              - type
              - amount
            properties:
              type:
                type: string
                enum:
                  - flat
                  - variable
                description: >-
                  The type of fee. `flat` is a fixed amount in the source
                  currency. `variable` is a percentage of the source amount.
              amount:
                type: string
                description: >-
                  The fee amount. For `flat` fees, this is the amount in the
                  source currency (e.g., `1.00` for $1.00). For `variable` fees,
                  this is a percentage (e.g., `2.5` for 2.5%).
    PaymentRoute:
      type: object
      required:
        - id
        - source
        - destination
        - status
        - depositAddress
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the payment route
        userId:
          type: string
          format: uuid
          description: User ID (present for individual teams; omit for company teams)
        companyId:
          type: string
          format: uuid
          description: Company ID (present for company teams; omit for individual teams)
        status:
          $ref: '#/components/schemas/PaymentRouteStatus'
        source:
          $ref: '#/components/schemas/AutomationSource'
        destination:
          $ref: '#/components/schemas/AutomationDestination'
        depositAddress:
          oneOf:
            - $ref: '#/components/schemas/AutomationFiatDepositAddress'
            - $ref: '#/components/schemas/AutomationOnchainDepositAddress'
          description: The deposit address for funds to be sent to this payment route
        refundAddress:
          type: string
          description: >-
            The onchain address where funds are returned if a transaction cannot
            be completed. Present when the source is a crypto rail.
        senderFees:
          type: array
          description: >-
            Array of sender fee configurations for this payment route. Present
            when sender fees are configured.
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - flat
                  - variable
                description: The type of fee
              amount:
                type: string
                description: The fee amount
        developerFees:
          type: array
          deprecated: true
          description: >-
            Deprecated: use `senderFees` instead. Returns the same values as
            `senderFees` for backward compatibility.
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - flat
                  - variable
                description: The type of fee
              amount:
                type: string
                description: The fee amount
        createdAt:
          type: string
          format: date-time
          description: When the payment route was created
        updatedAt:
          type: string
          format: date-time
          description: When the payment route was last updated
    ErrorResponse:
      type: object
      required:
        - statusCode
        - error
      properties:
        statusCode:
          type: number
          description: Status code indicating the request failed
        error:
          type: string
          description: >-
            Error type name, e.g. 'NotFoundError', 'BadRequestError',
            'InternalServerError'
        message:
          type: string
          description: Human-readable error message describing what went wrong
    AutomationSource:
      oneOf:
        - title: Crypto Source
          type: object
          description: Crypto source configuration
          required:
            - currency
            - rail
          properties:
            currency:
              $ref: '#/components/schemas/AutomationCryptoCurrency'
            rail:
              $ref: '#/components/schemas/AutomationCryptoRail'
        - title: Fiat Source
          type: object
          description: Fiat source configuration
          required:
            - currency
            - rail
          properties:
            currency:
              $ref: '#/components/schemas/AutomationFiatCurrency'
            rail:
              $ref: '#/components/schemas/AutomationFiatRail'
    AutomationDestination:
      oneOf:
        - title: Onchain Destination
          type: object
          description: Onchain destination with direct address
          required:
            - currency
            - rail
            - address
          properties:
            currency:
              $ref: '#/components/schemas/AutomationCryptoCurrency'
            rail:
              $ref: '#/components/schemas/AutomationCryptoRail'
            address:
              $ref: '#/components/schemas/AutomationOnchainAddress'
        - title: Fiat Destination
          type: object
          description: Fiat destination via payment account
          required:
            - currency
            - rail
            - address
          properties:
            currency:
              $ref: '#/components/schemas/AutomationFiatCurrency'
            rail:
              $ref: '#/components/schemas/AutomationFiatRail'
            address:
              $ref: '#/components/schemas/AutomationPaymentAccountAddress'
            referenceId:
              type: string
              description: Optional reference ID for the fiat transfer
    PaymentRouteStatus:
      type: string
      enum:
        - active
        - frozen
        - deleted
      description: Status of the payment route
    AutomationFiatDepositAddress:
      title: Fiat Deposit Address
      type: object
      required:
        - type
        - beneficiaryName
        - beneficiaryAddress
        - beneficiaryBankName
        - beneficiaryBankAddress
        - accountNumber
        - routingNumber
      properties:
        type:
          type: string
          enum:
            - fiat
        beneficiaryName:
          type: string
          description: Name of the beneficiary
        beneficiaryAddress:
          type: string
          description: Address of the beneficiary
        beneficiaryBankName:
          type: string
          description: Name of the beneficiary's bank
        beneficiaryBankAddress:
          type: string
          description: Address of the beneficiary's bank
        accountNumber:
          type: string
          description: Bank account number
        routingNumber:
          type: string
          description: Bank routing number
        transferMessage:
          type: string
          description: Message to include with the transfer
    AutomationOnchainDepositAddress:
      title: Onchain Deposit Address
      type: object
      required:
        - type
        - address
      properties:
        type:
          type: string
          enum:
            - onchain
        address:
          type: string
          description: The blockchain deposit address
    AutomationCryptoCurrency:
      type: string
      enum:
        - usdc
        - rusd
      description: Supported cryptocurrencies
    AutomationCryptoRail:
      type: string
      enum:
        - ethereum
        - polygon
        - optimism
        - arbitrum
        - avalanche
        - base
        - celo
        - solana
      description: Supported blockchain networks for crypto operations
    AutomationFiatCurrency:
      type: string
      enum:
        - usd
      description: Supported fiat currencies
    AutomationFiatRail:
      type: string
      enum:
        - ach
        - wire
      description: Supported fiat payment rails
    AutomationOnchainAddress:
      type: object
      required:
        - type
        - address
      properties:
        type:
          type: string
          enum:
            - onchain
        address:
          type: string
          description: The blockchain address
    AutomationPaymentAccountAddress:
      type: object
      required:
        - type
        - id
      properties:
        type:
          type: string
          enum:
            - paymentAccount
        id:
          type: string
          format: uuid
          description: The payment account ID
  examples:
    CreateAutomationRequestExample:
      value:
        userId: 11111111-1111-1111-1111-111111111111
        source:
          currency: usd
          rail: ach
        destination:
          currency: usdc
          rail: base
          address:
            type: onchain
            address: '0x1234567890abcdef1234567890abcdef12345678'
    AutomationExample:
      value:
        id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        userId: 11111111-1111-1111-1111-111111111111
        status: active
        source:
          currency: usd
          rail: ach
        destination:
          currency: usdc
          rail: base
          address:
            type: onchain
            address: '0x1234567890abcdef1234567890abcdef12345678'
        depositAddress:
          type: fiat
          beneficiaryName: RAIN PAYMENTS INC
          beneficiaryAddress: 123 Finance St, New York, NY 10001, US
          beneficiaryBankName: Partner Bank, N.A.
          beneficiaryBankAddress: 456 Bank Ave, New York, NY 10002, US
          accountNumber: '9876543210'
          routingNumber: '021000021'
          transferMessage: REF-A1B2C3D4
        createdAt: '2025-01-15T10:00:00Z'
        updatedAt: '2025-01-15T10:00:00Z'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: Api-Key
      in: header

````