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

# Create Crypto Bridge Deposit

> Enables cross-border transactions using blockchain as settlement rail. Provider initiates the transaction with a pre-generated payment invoice. Flow: Fiat collection → Crypto payment → Settlement to recipient. Supports Lightning Network, Solana, Base, Ethereum, and other chains. Supports mobile money and bank transfer settlements.



## OpenAPI

````yaml POST /api/v3/deposit/crypto-bridge
openapi: 3.0.0
info:
  title: KOTANI PAY API PLATFORM
  description: ''
  version: '3.0'
  contact: {}
servers:
  - url: https://preview.kotanipay.com
security: []
tags: []
paths:
  /api/v3/deposit/crypto-bridge:
    post:
      tags:
        - CRYPTO BRIDGE DEPOSIT
      summary: Create crypto bridge deposit (Cross-border remittances)
      description: >-
        Enables cross-border transactions using blockchain as settlement rail.
        Provider initiates the transaction with a pre-generated payment invoice.
        Flow: Fiat collection → Crypto payment → Settlement to recipient.
        Supports Lightning Network, Solana, Base, Ethereum, and other chains.
        Supports mobile money and bank transfer settlements.
      operationId: DepositCryptoBridgeController_createCryptoBridgeDeposit_api/v3
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCryptoBridgeDepositDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Crypto bridge deposit initiated successfully.
                  data:
                    $ref: '#/components/schemas/CryptoBridgeDepositResponseDto'
                    type: object
        '400':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Bad Request
                  data:
                    type: object
                    example: {}
        '401':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Unauthorized
                  data:
                    type: object
                    example: {}
        '422':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Invalid invoice or payment details
                  data:
                    type: object
                    example: {}
      security:
        - JWT: []
components:
  schemas:
    CreateCryptoBridgeDepositDto:
      type: object
      properties:
        rate_id:
          type: string
          description: >-
            Rate ID from /rate/crypto-bridge endpoint. Optional but recommended.
            Validates fiat->crypto conversion rate. Rate expires in 60 seconds.
          example: RATE-CB-1732454321-XYZ123
        customer_key:
          type: string
          description: Customer key (Provider customer ID in Kotani system)
          example: PROVIDER_CUSTOMER_123
        provider_reference_id:
          type: string
          description: Provider's unique transaction reference ID
          example: PROVIDER-TXN-20241122-001
        amount:
          type: number
          description: Source fiat amount
          example: 1000
        source_currency:
          type: string
          description: Source fiat currency code
          example: KES
        wallet_id:
          type: string
          description: Kotani wallet ID to use for transaction
          example: KOTANI_WALLET_ID
        transaction_type:
          type: string
          enum:
            - cross_border
            - bridge
            - chain_settlement
          description: Type of bridge transaction
          example: cross_border
        chain:
          type: string
          enum:
            - CELO
            - ETHEREUM
            - ARBITRUM
            - AVALANCHE
            - BINANCE
            - POLYGON
            - OPTIMISM
            - FUSE
            - TRON
            - PROVENANCE
            - SOLANA
            - HEDERA
            - STELLAR
            - BASE
            - LISK
            - VICTION
            - SCROLL
            - LIGHTNING
          description: Blockchain/network to use
          example: LIGHTNING
        token:
          type: string
          enum:
            - CUSD
            - USDC
            - USDT
            - BUSD
            - HASH
            - HBAR
            - USDGLO
            - CKES
            - CGHS
            - MSAT
          description: Token/asset to use
          example: MSAT
        crypto_payment:
          description: Crypto payment details (pre-generated invoice or address)
          allOf:
            - $ref: '#/components/schemas/CryptoPaymentDto'
        settlement:
          description: Settlement details for recipient
          allOf:
            - $ref: '#/components/schemas/SettlementDto'
        callback_url:
          type: string
          description: Callback URL for status updates
          example: https://api.provider.com/webhooks/kotani/status
        metadata:
          description: Additional transaction metadata
          allOf:
            - $ref: '#/components/schemas/TransactionMetadataDto'
      required:
        - customer_key
        - provider_reference_id
        - amount
        - source_currency
        - wallet_id
        - transaction_type
        - chain
        - token
        - crypto_payment
        - settlement
        - callback_url
    CryptoBridgeDepositResponseDto:
      type: object
      properties:
        kotani_reference_id:
          type: string
          description: Kotani reference ID for tracking
          example: KOTANI-REF-789
        provider_reference_id:
          type: string
          description: Provider reference ID (echoed back)
          example: PROVIDER-TXN-20241122-001
        status:
          type: string
          enum:
            - DEPOSIT_INITIATED
            - DEPOSIT_CONFIRMED
            - PAYMENT_SENT
            - PAYMENT_CONFIRMED
            - SETTLING
            - COMPLETED
            - FAILED
            - REFUNDED
          description: Current transaction status
          example: DEPOSIT_INITIATED
        chain:
          type: string
          enum:
            - CELO
            - ETHEREUM
            - ARBITRUM
            - AVALANCHE
            - BINANCE
            - POLYGON
            - OPTIMISM
            - FUSE
            - TRON
            - PROVENANCE
            - SOLANA
            - HEDERA
            - STELLAR
            - BASE
            - LISK
            - VICTION
            - SCROLL
            - LIGHTNING
          description: Chain being used
          example: LIGHTNING
        token:
          type: string
          enum:
            - CUSD
            - USDC
            - USDT
            - BUSD
            - HASH
            - HBAR
            - USDGLO
            - CKES
            - CGHS
            - MSAT
          description: Token being used
          example: MSAT
        payment_hash:
          type: string
          description: Payment hash for tracking crypto transaction
          example: a1b2c3d4e5f6...
        refund_config:
          description: >-
            Refund configuration - Orange must pay this invoice/address if
            settlement fails to return crypto to Kotani
          allOf:
            - $ref: '#/components/schemas/RefundConfigDto'
        estimated_completion:
          type: string
          description: Estimated completion time (ISO 8601)
          example: '2024-11-22T12:10:00Z'
        created_at:
          type: string
          description: Transaction creation timestamp (ISO 8601)
          example: '2024-11-22T12:00:00Z'
      required:
        - kotani_reference_id
        - provider_reference_id
        - status
        - chain
        - token
        - payment_hash
        - refund_config
        - estimated_completion
        - created_at
    CryptoPaymentDto:
      type: object
      properties:
        bolt11:
          type: string
          description: Lightning bolt11 invoice (for Lightning Network)
          example: lnbc1500n1p0xyz...
        payment_hash:
          type: string
          description: Payment hash
          example: a1b2c3d4e5f6...
        amount_msat:
          type: number
          description: Amount in millisatoshis (for Lightning)
          example: 150000000
        address:
          type: string
          description: Crypto wallet address (for non-Lightning chains)
          example: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
        crypto_amount:
          type: number
          description: Crypto amount (for non-Lightning chains)
          example: 150.5
        expires_at:
          type: string
          description: Invoice expiration timestamp (ISO 8601)
          example: '2024-11-22T12:30:00Z'
    SettlementDto:
      type: object
      properties:
        amount:
          type: number
          description: Settlement amount in destination currency
          example: 150
        currency:
          type: string
          description: Destination fiat currency code
          example: ZAR
        country:
          type: string
          description: Destination country code (ISO 3166-1 alpha-2)
          example: ZA
        recipient:
          description: Recipient payment details
          allOf:
            - $ref: '#/components/schemas/RecipientDto'
      required:
        - amount
        - currency
        - country
        - recipient
    TransactionMetadataDto:
      type: object
      properties:
        sender_name:
          type: string
          description: Sender name
          example: John Doe
        sender_country:
          type: string
          description: Sender country code
          example: KE
        recipient_name:
          type: string
          description: Recipient name
          example: Jane Smith
        recipient_country:
          type: string
          description: Recipient country code
          example: ZA
        notes:
          type: string
          description: Additional notes or context
          example: Family support payment
    RefundConfigDto:
      type: object
      properties:
        primary_method:
          type: string
          enum:
            - CRYPTO_INVOICE
            - CRYPTO_ADDRESS
          description: Primary refund method - How Orange should return crypto to Kotani
          example: CRYPTO_INVOICE
        chain:
          type: string
          enum:
            - CELO
            - ETHEREUM
            - ARBITRUM
            - AVALANCHE
            - BINANCE
            - POLYGON
            - OPTIMISM
            - FUSE
            - TRON
            - PROVENANCE
            - SOLANA
            - HEDERA
            - STELLAR
            - BASE
            - LISK
            - VICTION
            - SCROLL
            - LIGHTNING
          description: Blockchain/network for refund (same as transaction chain)
          example: LIGHTNING
        token:
          type: string
          enum:
            - CUSD
            - USDC
            - USDT
            - BUSD
            - HASH
            - HBAR
            - USDGLO
            - CKES
            - CGHS
            - MSAT
          description: Token for refund (same as transaction token)
          example: MSAT
        refund_invoice:
          type: string
          description: >-
            Kotani refund invoice (for Lightning) - Orange pays this if
            settlement fails
          example: lnbc1500n1p0xyz...
        refund_payment_hash:
          type: string
          description: Refund payment hash for tracking
          example: a1b2c3d4e5f6...
        refund_amount_msat:
          type: number
          description: Refund amount in millisatoshis (for Lightning)
          example: 150000000
        refund_crypto_amount:
          type: number
          description: Refund crypto amount (for non-Lightning chains)
          example: 150.5
        fallback_address:
          type: string
          description: >-
            Kotani crypto address for refund (if invoice not applicable) -
            Orange sends to this address if settlement fails
          example: bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh
        fallback_method:
          type: string
          enum:
            - CRYPTO_INVOICE
            - CRYPTO_ADDRESS
          description: Fallback refund method if primary method fails
          example: CRYPTO_ADDRESS
        expires_at:
          type: string
          description: Invoice expiration time (ISO 8601)
          example: '2024-11-22T13:00:00Z'
      required:
        - primary_method
        - chain
        - token
    RecipientDto:
      type: object
      properties:
        phone_number:
          type: string
          description: Recipient phone number (required for all payment methods)
          example: '+27821234567'
        payment_method:
          type: string
          enum:
            - MOBILE_MONEY
            - BANK_TRANSFER
          description: Payment method for recipient
          example: MOBILE_MONEY
        mobile_money_provider:
          type: string
          description: Mobile money provider (required for MOBILE_MONEY)
          example: VODACOM
        bank_account_number:
          type: string
          description: Bank account number (required for BANK_TRANSFER)
          example: '1234567890'
        bank_code:
          type: string
          description: Bank code (required for BANK_TRANSFER)
          example: ABSA
        account_holder_name:
          type: string
          description: Account holder name (required for BANK_TRANSFER)
          example: Jane Smith
      required:
        - phone_number
        - payment_method
  securitySchemes:
    JWT:
      scheme: bearer
      bearerFormat: JWT
      type: http

````