Coinflow subMerchant API

openapi: 3.1.0
info:
  title: API Reference authentication subMerchant API
  version: 1.0.0
servers:
- url: https://api-sandbox.coinflow.cash/api
  description: https://api-sandbox.coinflow.cash/api
tags:
- name: subMerchant
paths:
  /submerchant:
    get:
      operationId: get-submerchants
      summary: Get All Submerchants
      tags:
      - subMerchant
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: number
          format: double
          default: 1
      - name: limit
        in: query
        required: false
        schema:
          type: number
          format: double
          default: 100
      - name: search
        in: query
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: The API key of the merchant - see https://docs.coinflow.cash/api-reference/api-reference/authentication/get-session-key
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SanitizedMerchant'
  /submerchant/{submerchantId}:
    get:
      operationId: get-submerchant
      summary: Get Submerchant by ID
      tags:
      - subMerchant
      parameters:
      - name: submerchantId
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: The API key of the merchant - see https://docs.coinflow.cash/api-reference/api-reference/authentication/get-session-key
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SanitizedMerchant'
        '404':
          description: Submerchant Not Found
          content:
            application/json:
              schema:
                description: Any type
  /submerchant/onboarding-token:
    post:
      operationId: get-onboarding-token
      summary: Get Submerchant Onboarding Token
      description: 'Mint a short-lived onboarding token that authorizes creating a

        submerchant or seller under the authenticated merchant. The token embeds

        the caller''s own merchantId as the parent — it cannot be minted for

        another merchant.'
      tags:
      - subMerchant
      parameters:
      - name: Authorization
        in: header
        description: The API key of the merchant - see https://docs.coinflow.cash/api-reference/api-reference/authentication/get-session-key
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubMerchant_GetOnboardingToken_Response_200'
components:
  schemas:
    PayPalPayoutProvider:
      type: string
      enum:
      - checkbook
      - citcon
      - mock
      - paypal
      title: PayPalPayoutProvider
    Currency:
      type: string
      enum:
      - USD
      - AED
      - AFN
      - ALL
      - AMD
      - ANG
      - AOA
      - ARS
      - AUD
      - AWG
      - AZN
      - BAM
      - BBD
      - BDT
      - BGN
      - BHD
      - BIF
      - BMD
      - BND
      - BOB
      - BRL
      - BSD
      - BTN
      - BWP
      - BYN
      - BZD
      - CAD
      - CHF
      - CLF
      - CLP
      - CNY
      - COP
      - CRC
      - CUP
      - CVE
      - CZK
      - DJF
      - DKK
      - DOP
      - DZD
      - EGP
      - ETB
      - EUR
      - FJD
      - GBP
      - GEL
      - GHS
      - GMD
      - GNF
      - GTQ
      - GYD
      - HKD
      - HNL
      - HTG
      - HUF
      - IDR
      - ILS
      - INR
      - IQD
      - IRR
      - ISK
      - JMD
      - JOD
      - JPY
      - KES
      - KGS
      - KHR
      - KMF
      - KRW
      - KWD
      - KYD
      - KZT
      - LAK
      - LBP
      - LKR
      - LRD
      - LSL
      - LYD
      - MAD
      - MDL
      - MGA
      - MKD
      - MMK
      - MNT
      - MOP
      - MRU
      - MUR
      - MWK
      - MVR
      - MXN
      - MYR
      - MZN
      - NAD
      - NGN
      - NIO
      - NOK
      - NPR
      - NZD
      - OMR
      - PAB
      - PEN
      - PGK
      - PHP
      - PKR
      - PLN
      - PYG
      - QAR
      - RON
      - RSD
      - RWF
      - SAR
      - SCR
      - SDG
      - SEK
      - SGD
      - SLE
      - SLL
      - SOS
      - SRD
      - STN
      - SVC
      - SYP
      - SZL
      - THB
      - TJS
      - TMT
      - TND
      - TOP
      - TRY
      - TTD
      - TWD
      - TZS
      - UAH
      - UGX
      - UYU
      - UZS
      - VND
      - VUV
      - WST
      - XAF
      - XCD
      - XOF
      - XPF
      - YER
      - ZAR
      - ZMW
      - ZWL
      - CDF
      - ERN
      - FKP
      - KPW
      - RUB
      - SBD
      - SHP
      - SSP
      - VES
      title: Currency
    PortalBrand:
      type: string
      enum:
      - approvely
      - seamlesschex
      - coinflow
      - yourbrandhere
      - Plan2Play
      - tango
      - interlace
      - tapvia
      title: PortalBrand
    TokenizationProviderOption:
      type: string
      enum:
      - bt
      - tokenex
      title: TokenizationProviderOption
    RtpPayoutProvider:
      type: string
      enum:
      - dwolla
      - mock
      - aptpay
      - aptpayRtp
      - checkbook
      - brale
      title: RtpPayoutProvider
    FeePayerMode:
      type: string
      enum:
      - user
      - merchant
      - invoice
      title: FeePayerMode
    VenmoPayoutProvider:
      type: string
      enum:
      - checkbook
      - citcon
      - mock
      - paypal
      title: VenmoPayoutProvider
    SanitizedMerchantCardSettings:
      type: object
      properties:
        statementDescriptor:
          type: string
        saveCardDefault:
          type: boolean
        processor:
          $ref: '#/components/schemas/PaymentProcessor'
        googlePayProcessor:
          $ref: '#/components/schemas/PaymentProcessor'
        applePayProcessor:
          $ref: '#/components/schemas/PaymentProcessor'
        supportsApplePay:
          type: boolean
        supportsGooglePay:
          type: boolean
        tokenizationProvider:
          $ref: '#/components/schemas/TokenizationProviderOption'
        avsCheck:
          type: boolean
        requiresKyc:
          type: boolean
        aftEnabled:
          type: boolean
      required:
      - avsCheck
      - requiresKyc
      - aftEnabled
      description: From T, pick a set of properties whose keys are in the union K
      title: SanitizedMerchantCardSettings
    CustomPayInFeeValue0:
      type: object
      properties:
        cents:
          type: number
          format: double
        currency:
          $ref: '#/components/schemas/Currency'
        percent:
          type:
          - number
          - 'null'
          format: double
        isFixed:
          type: boolean
      required:
      - cents
      - currency
      - percent
      - isFixed
      title: CustomPayInFeeValue0
    CustomPayInFeeValue1:
      type: object
      properties:
        cents:
          type:
          - number
          - 'null'
          format: double
        currency:
          type:
          - number
          - 'null'
          format: double
        percent:
          type: number
          format: double
        isFixed:
          type: boolean
      required:
      - cents
      - currency
      - percent
      - isFixed
      title: CustomPayInFeeValue1
    PayoutProviderOption:
      type: string
      enum:
      - aptpay
      - coinfx
      - checkbook
      - BRAID
      - brale
      - mock
      title: PayoutProviderOption
    CustomPayInFeeConfig:
      type: object
      properties:
        fee:
          $ref: '#/components/schemas/CustomPayInFeeValue'
        lineItemLabel:
          type: string
      required:
      - fee
      - lineItemLabel
      title: CustomPayInFeeConfig
    CustomPayInFeeValue:
      oneOf:
      - $ref: '#/components/schemas/CustomPayInFeeValue0'
      - $ref: '#/components/schemas/CustomPayInFeeValue1'
      title: CustomPayInFeeValue
    WirePayoutProvider:
      type: string
      enum:
      - MOCK
      - BRAID
      title: WirePayoutProvider
    EftPayoutProvider:
      type: string
      enum:
      - checkbook
      - aptpay
      - mock
      title: EftPayoutProvider
    IbanPayoutProvider:
      type: string
      enum:
      - merge
      - mock
      - ivy
      title: IbanPayoutProvider
    InteracProcessor:
      type: string
      enum:
      - mock
      - aptpay
      title: InteracProcessor
    Cents:
      type: object
      properties:
        cents:
          type: integer
      required:
      - cents
      title: Cents
    PixPayoutProvider:
      type: string
      enum:
      - brla
      - mock
      title: PixPayoutProvider
    MerchantStyle:
      type: string
      enum:
      - rounded
      - sharp
      - pill
      title: MerchantStyle
    InteracPayoutProvider:
      type: string
      enum:
      - checkbook
      - mock
      - aptpay
      title: InteracPayoutProvider
    KycType:
      type: string
      enum:
      - person
      - business
      - both
      title: KycType
    MerchantBrandSettings:
      type: object
      properties:
        portalBrand:
          $ref: '#/components/schemas/PortalBrand'
        logo:
          type: string
        displayName:
          type: string
      title: MerchantBrandSettings
    ApplePayPayoutProvider:
      type: string
      enum:
      - aptpay
      - MOCK
      title: ApplePayPayoutProvider
    SanitizedMerchantSettlementAddresses:
      type: object
      properties:
        solana:
          type: string
        eth:
          type: string
        polygon:
          type: string
        base:
          type: string
        user:
          type: string
        arbitrum:
          type: string
        stellar:
          type: string
        monad:
          type: string
        tempo:
          type: string
      title: SanitizedMerchantSettlementAddresses
    Pick_ACHSettings.instantSettle-or-requireKycBeforePurchase_:
      type: object
      properties:
        instantSettle:
          type: boolean
        requireKycBeforePurchase:
          type: boolean
      required:
      - instantSettle
      description: From T, pick a set of properties whose keys are in the union K
      title: Pick_ACHSettings.instantSettle-or-requireKycBeforePurchase_
    CustomPayInFeesConfig:
      type: array
      items:
        $ref: '#/components/schemas/CustomPayInFeeConfig'
      title: CustomPayInFeesConfig
    MerchantTheme:
      type: object
      properties:
        showCardIcon:
          type: boolean
        placeholderColor:
          type: string
        expirationPlaceholder:
          type: string
        cvvPlaceholder:
          type: string
        cardNumberPlaceholder:
          type: string
        fontWeight:
          type: string
        fontSize:
          type: string
        style:
          $ref: '#/components/schemas/MerchantStyle'
        font:
          type: string
        ctaColor:
          type: string
        textColorAction:
          type: string
        textColorAccent:
          type: string
        textColor:
          type: string
        backgroundAccent2:
          type: string
        backgroundAccent:
          type: string
        cardBackground:
          type: string
        background:
          type: string
        primary:
          type: string
      title: MerchantTheme
    InteracSettings:
      type: object
      properties:
        processor:
          $ref: '#/components/schemas/InteracProcessor'
        feeMode:
          $ref: '#/components/schemas/FeePayerMode'
        fxFeeMode:
          $ref: '#/components/schemas/FeePayerMode'
        fixedFee:
          $ref: '#/components/schemas/Cents'
        feeBps:
          type: number
          format: double
        minFee:
          $ref: '#/components/schemas/Cents'
        customerEmailNotifications:
          type: boolean
        merchantEmailNotifications:
          type: boolean
      required:
      - customerEmailNotifications
      - merchantEmailNotifications
      title: InteracSettings
    SanitizedMerchantFirstPartyPayoutOverrides:
      type: object
      properties:
        interacPayoutProvider:
          $ref: '#/components/schemas/InteracPayoutProvider'
        wirePayoutProvider:
          type: array
          items:
            $ref: '#/components/schemas/WirePayoutProvider'
        paypalPayoutProvider:
          $ref: '#/components/schemas/PayPalPayoutProvider'
        venmoPayoutProvider:
          $ref: '#/components/schemas/VenmoPayoutProvider'
        appleP2cPayoutProvider:
          $ref: '#/components/schemas/ApplePayPayoutProvider'
        globalP2cPayoutProvider:
          $ref: '#/components/schemas/CardPayoutProvider'
        p2cPayoutProvider:
          $ref: '#/components/schemas/CardPayoutProvider'
        eftPayoutProvider:
          $ref: '#/components/schemas/EftPayoutProvider'
        pixPayoutProvider:
          $ref: '#/components/schemas/PixPayoutProvider'
        rtpPayoutProvider:
          $ref: '#/components/schemas/RtpPayoutProvider'
        ibanPayoutProvider:
          $ref: '#/components/schemas/IbanPayoutProvider'
        bankPayoutProvider:
          type: array
          items:
            $ref: '#/components/schemas/PayoutProviderOption'
      title: SanitizedMerchantFirstPartyPayoutOverrides
    SanitizedMerchant:
      type: object
      properties:
        _id:
          type: string
        merchantId:
          type: string
        brand:
          $ref: '#/components/schemas/MerchantBrandSettings'
        colors:
          $ref: '#/components/schemas/MerchantTheme'
        url:
          type: string
        kycType:
          $ref: '#/components/schemas/KycType'
        settlementAddresses:
          $ref: '#/components/schemas/SanitizedMerchantSettlementAddresses'
        hideBranding:
          type: boolean
        onlyShowTotal:
          type: boolean
        pushToCardEnabled:
          type: boolean
        requireAniCheck:
          type: boolean
        bankPayoutProvider:
          type: array
          items:
            $ref: '#/components/schemas/PayoutProviderOption'
        ibanPayoutProviders:
          type: array
          items:
            $ref: '#/components/schemas/IbanPayoutProvider'
        ibanPayoutProvider:
          $ref: '#/components/schemas/IbanPayoutProvider'
        rtpPayoutProviders:
          type: array
          items:
            $ref: '#/components/schemas/RtpPayoutProvider'
        rtpPayoutProvider:
          $ref: '#/components/schemas/RtpPayoutProvider'
        pixPayoutProviders:
          type: array
          items:
            $ref: '#/components/schemas/PixPayoutProvider'
        pixPayoutProvider:
          $ref: '#/components/schemas/PixPayoutProvider'
        eftPayoutProviders:
          type: array
          items:
            $ref: '#/components/schemas/EftPayoutProvider'
        eftPayoutProvider:
          $ref: '#/components/schemas/EftPayoutProvider'
        p2cPayoutProviders:
          type: array
          items:
            $ref: '#/components/schemas/CardPayoutProvider'
        p2cPayoutProvider:
          $ref: '#/components/schemas/CardPayoutProvider'
        globalP2cPayoutProvider:
          $ref: '#/components/schemas/CardPayoutProvider'
        appleP2cPayoutProvider:
          $ref: '#/components/schemas/ApplePayPayoutProvider'
        venmoPayoutProviders:
          type: array
          items:
            $ref: '#/components/schemas/VenmoPayoutProvider'
        venmoPayoutProvider:
          $ref: '#/components/schemas/VenmoPayoutProvider'
        paypalPayoutProviders:
          type: array
          items:
            $ref: '#/components/schemas/PayPalPayoutProvider'
        paypalPayoutProvider:
          $ref: '#/components/schemas/PayPalPayoutProvider'
        wirePayoutProvider:
          type: array
          items:
            $ref: '#/components/schemas/WirePayoutProvider'
        interacPayoutProviders:
          type: array
          items:
            $ref: '#/components/schemas/InteracPayoutProvider'
        interacPayoutProvider:
          $ref: '#/components/schemas/InteracPayoutProvider'
        interacPaymentProvider:
          $ref: '#/components/schemas/InteracProcessor'
        interacSettings:
          $ref: '#/components/schemas/InteracSettings'
        firstPartyPayoutOverrides:
          $ref: '#/components/schemas/SanitizedMerchantFirstPartyPayoutOverrides'
        creditSeed:
          type: string
        enforceJwt:
          type: boolean
        enforceCheckoutJwt:
          type: boolean
        externalVerificationLinks:
          type: boolean
        whitelistedAncestorUrls:
          type: array
          items:
            type: string
        enforceLivenessKyc:
          type: boolean
        feePayerPublicKey:
          type: string
        solanaFeePayerPublicKey:
          type: string
        solanaUsdcPayerPublicKey:
          type: string
        evmFeePayerAddress:
          type: string
        evmUsdcPayerAddress:
          type: string
        stellarUsdcPayerPublicKey:
          type: string
        _sanitized:
          type: boolean
        parent:
          type: string
        customPayInFees:
          $ref: '#/components/schemas/CustomPayInFeesConfig'
        cardSettings:
          $ref: '#/components/schemas/SanitizedMerchantCardSettings'
        achSettings:
          $ref: '#/components/schemas/Pick_ACHSettings.instantSettle-or-requireKycBeforePurchase_'
        verification:
          $ref: '#/components/schemas/Pick_Verification.status_'
        canAcceptAch:
          type: boolean
        canAcceptWire:
          type: boolean
        minTransactionAmount:
          $ref: '#/components/schemas/Cents'
        maxTransactionAmount:
          $ref: '#/components/schemas/Cents'
        withdrawalGeolocationRequired:
          type: boolean
          description: 'Authoritative: derived from the merchant''s blockingRules. The frontend

            uses this to decide whether to prompt for geolocation; the backend

            enforces independently via the same rules.'
        checkoutGeolocationRequired:
          type: boolean
        paypalMerchantId:
          type: string
        paypalClientId:
          type: string
      required:
      - _id
      - merchantId
      - kycType
      - hideBranding
      - onlyShowTotal
      - pushToCardEnabled
      - requireAniCheck
      - interacSettings
      - creditSeed
      - enforceJwt
      - feePayerPublicKey
      - solanaFeePayerPublicKey
      - solanaUsdcPayerPublicKey
      - evmFeePayerAddress
      - evmUsdcPayerAddress
      - stellarUsdcPayerPublicKey
      - _sanitized
      - cardSettings
      - achSettings
      - verification
      - canAcceptAch
      - canAcceptWire
      - withdrawalGeolocationRequired
      - checkoutGeolocationRequired
      title: SanitizedMerchant
    Pick_Verification.status_:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/VerificationStatus'
      required:
      - status
      description: From T, pick a set of properties whose keys are in the union K
      title: Pick_Verification.status_
    PaymentProcessor:
      type: string
      enum:
      - payarc
      - mock
      - shift4
      - merchant_warrior
      - greenlight
      - frame
      - nmi_direct
      - mvb
      - fifththird
      - natwest
      - nuveiv1
      - fallback_payarc_shift4
      - fallback_shift4_payarc
      - fallback_shift4_nuvei
      - fallback_nuvei_payarc
      - fallback_payarc_nuvei
      - fallback_shift4_greenlight
      - fallback_greenlight_shift4
      - fallback_frame_merchant_warrior
      - fallback_merchant_warrior_frame
      - fallback_natwest_shift4
      - fallback_natwest_nuvei
      - fallback_natwest_shift4_payarc
      - fallback_natwest_shift4_nuvei
      - fallback_shift4_natwest_payarc
      - fallback_nuvei_natwest_payarc
      - fallback_natwest_nuvei_payarc
      - fallback_mvb_fifththird_shift4_payarc
      - fallback_fifththird_mvb_shift4_payarc
      - fallback_mvb_nuvei
      - fallback_nuvei_fifththird
      - fallback_fifththird_nuvei
      title: PaymentProcessor
    VerificationStatus:
      type: string
      enum:
      - pending
      - partial-approval
      - approved
      - rejected
      - expired
      title: VerificationStatus
    CardPayoutProvider:
      type: string
      enum:
      - aptpay
      - checkbook
      - shift4
      - MOCK
      title: CardPayoutProvider
    SubMerchant_GetOnboardingToken_Response_200:
      type: object
      properties:
        token:
          type: string
      required:
      - token
      title: SubMerchant_GetOnboardingToken_Response_200
  securitySchemes:
    wallet:
      type: apiKey
      in: header
      name: x-coinflow-auth-wallet
      description: The web3 wallet of the end user - see https://docs.coinflow.cash/api-reference/api-reference/authentication/get-session-key
    blockchain:
      type: apiKey
      in: header
      name: x-coinflow-auth-blockchain
      description: The blockchain associated with the end user - see https://docs.coinflow.cash/api-reference/api-reference/authentication/get-session-key
    userId:
      type: apiKey
      in: header
      name: x-coinflow-auth-user-id
      description: The external identifier of the end user - see https://docs.coinflow.cash/api-reference/api-reference/authentication/get-session-key
    merchant:
      type: apiKey
      in: header
      name: Authorization
      description: The API key of the merchant - see https://docs.coinflow.cash/api-reference/api-reference/authentication/get-session-key
    signedMessage:
      type: apiKey
      in: header
      name: x-coinflow-auth-signed-message
      description: The message signed by the users wallet
    merchantId:
      type: apiKey
      in: header
      name: x-coinflow-auth-merchant-id
      description: The merchant ID the session should be generated for
    sessionKey:
      type: apiKey
      in: header
      name: x-coinflow-auth-session-key
      description: The session key generated for the end user - see https://docs.coinflow.cash/api-reference/api-reference/authentication/get-session-key
    admin:
      type: apiKey
      in: header
      name: Authorization