> ## Documentation Index
> Fetch the complete documentation index at: https://docs.carbn.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Onramp Transfer

> Initiate a new onramp transfer



## OpenAPI

````yaml /api-reference/openapi.json post /payment/api/v1/transfers/onramp
openapi: 3.0.0
info:
  title: Carbn Connect API
  version: 1.0.0
  description: >-
    API documentation for Carbn Connect services including user onboarding, KYC,
    wallet management, and transfers.
servers:
  - url: https://api.carbnconnect.com
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /payment/api/v1/transfers/onramp:
    post:
      tags:
        - Payments
      summary: Onramp Transfer
      description: Initiate a new onramp transfer
      operationId: onrampTransfer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnrampTransferRequest'
      responses:
        '200':
          description: Onramp transfer initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnrampTransferResponse'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized - API key is missing or invalid
      security:
        - ApiKeyAuth: []
components:
  schemas:
    OnrampTransferRequest:
      type: object
      required:
        - user_id
        - wallet_id
      properties:
        user_id:
          type: string
          format: uuid
          example: 0abad22b-53d3-4473-b1ee-283f4b32e3ad
          description: The unique identifier of the user
        wallet_id:
          type: string
          format: uuid
          example: 34e9819d-2f1c-40a5-9404-a1be8fe34227
          description: The unique identifier of the wallet
        open_banking:
          type: object
          description: >-
            Open Banking payment options. When provided, the transfer uses the
            hosted Open Banking flow. Available for US, EU, and UK.
          required:
            - amount
            - redirect_url
            - is_mobile_app
          properties:
            amount:
              type: number
              example: 3
              description: The amount to transfer
            redirect_url:
              type: string
              format: uri
              example: https://www.google.com
              description: >-
                URL to redirect the user to after completing the Open Banking
                payment flow
            is_mobile_app:
              type: boolean
              example: false
              description: Whether the payment is initiated from a mobile app context
            country_codes:
              type: array
              items:
                type: string
              example:
                - SWE
              description: >-
                Optional list of country codes (ISO 3166-1 alpha-3) to filter
                available banks. When not provided, all supported bank countries
                for the user are available. When provided, only banks from the
                specified countries will be shown.
            institute_id:
              type: string
              example: ins_116580
              description: >-
                Optional. The unique identifier of a specific institution
                (retrieved from the Get Institutions endpoint). When provided,
                the user is taken directly to that institution's login page,
                bypassing the bank selection screen.
        qr_payin:
          type: object
          description: >-
            QR Payin payment options. Available exclusively for PHP (Philippine
            Peso) transactions. Generates a QR code that users can scan with
            their mobile banking app.
          required:
            - amount
          properties:
            amount:
              type: number
              example: 400
              description: 'The amount to transfer in PHP (minimum: 400 PHP)'
    OnrampTransferResponse:
      type: object
      properties:
        transaction_id:
          type: string
          format: uuid
          nullable: true
          example: 76e12d55-1a25-457e-9e97-0495162de555
          description: The unique identifier of the transaction
        source_currency:
          type: string
          example: PHP
          description: Source currency code (ISO 4217)
        open_banking:
          type: object
          nullable: true
          description: Open Banking response data
          properties:
            deposit_link:
              type: string
              format: uri
              example: https://secure.plaid.com/hl/lpps56nr6p98sn9r89341n78s8834q672q
              description: URL for the Open Banking deposit flow
            payment_id:
              type: string
              example: payment-id-production-2308307c-0d61-46d3-9225-50d48f607e36
              description: Payment identifier
            link_token:
              type: string
              example: link-production-cf01ae1c-43fa-4e34-896a-23f3389d127d
              description: Link token for the Open Banking flow
        qr_payin:
          type: object
          nullable: true
          description: QR Payin response data (PHP only)
          properties:
            qr_code:
              type: string
              example: >-
                00020101021228600011ph.ppmi.p2m0111DCPHPHM1XXX03192147235668383093866050301152044814530360854034005802PH5904test6015MAHAGUN
                MORPHEU62380011ph.ppmi.p2m0519198581120859644569663048038
              description: QR code string that users can scan with their mobile banking app
            expiry_time:
              type: string
              format: date-time
              example: '2026-02-10T07:13:58.621Z'
              description: >-
                Expiration time for the QR code. Users must complete payment
                before this time.
        v_bank:
          type: object
          nullable: true
          description: Virtual bank account details
          properties:
            bic:
              type: string
              example: MODRIE22XXX
              description: Bank Identifier Code
            iban:
              type: string
              example: IE44MODR99035511728566
              description: International Bank Account Number
            bank_name:
              type: string
              example: Modulr Finance, Ireland Branch
              description: Name of the bank
            payment_rail:
              type: string
              example: sepa
              description: Payment rail used (sepa, swift, etc.)
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication. Must be included in the x-api-key header.

````