Coinflow merchant API

openapi: 3.1.0
info:
  title: API Reference authentication merchant API
  version: 1.0.0
servers:
- url: https://api-sandbox.coinflow.cash/api
  description: https://api-sandbox.coinflow.cash/api
tags:
- name: merchant
paths:
  /withdraw/crypto-deposit-address/activate:
    post:
      operationId: activate-passive-deposit-address
      summary: Activate Passive Deposit Address
      description: 'Activate a passive deposit address so it accepts new payments. If a deposit

        address already exists for this merchant + withdrawer + chain + token, that

        address is re-activated and returned. Otherwise a new session is created

        and its address is activated.'
      tags:
      - merchant
      parameters:
      - name: x-coinflow-auth-user-id
        in: header
        description: The external identifier of the end user - 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/PassiveDepositAddressStatusResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCryptoWithdrawBody'
  /merchant/block-seller:
    put:
      operationId: block-marketplace-seller
      summary: Bans a seller
      tags:
      - merchant
      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: Successful response
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlockSellerRequest'
  /merchant/blocked/{customerId}:
    put:
      operationId: unblock-account
      summary: Block or Unblock Customer
      tags:
      - merchant
      parameters:
      - name: customerId
        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: Successful response
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantId:
                  type: string
                reason:
                  type: string
                status:
                  $ref: '#/components/schemas/AvailabilityStatus'
              required:
              - reason
  /merchant/block-withdrawer/{withdrawerId}:
    put:
      operationId: block-or-unblock-withdrawer
      summary: Block or Unblock Withdrawer
      tags:
      - merchant
      parameters:
      - name: withdrawerId
        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: Successful response
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                blockchain:
                  $ref: '#/components/schemas/Blockchain'
                reason:
                  type: string
                status:
                  $ref: '#/components/schemas/AvailabilityStatus'
              required:
              - reason
              - status
  /merchant/{customerId}/exempt3DS:
    put:
      operationId: update-3-ds-exemption
      summary: Configure 3DS exemption
      description: Change customer 3DS exemption status
      tags:
      - merchant
      parameters:
      - name: customerId
        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: Successful response
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantId:
                  type: string
                exempt:
                  type: boolean
              required:
              - exempt
  /merchant/{customerId}/attemptLimit:
    put:
      operationId: update-attempt-limit-setting
      summary: Configure attempt limit setting
      description: Change customer attempt limit setting
      tags:
      - merchant
      parameters:
      - name: customerId
        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: Successful response
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantId:
                  type: string
                setting:
                  $ref: '#/components/schemas/FailedAttemptSetting'
              required:
              - setting
  /merchant/chargebacks/{paymentId}/respond:
    post:
      operationId: respond
      summary: Create Chargeback Response
      description: Respond to a chargeback. This will send the response to the card network.
      tags:
      - merchant
      parameters:
      - name: paymentId
        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: Successful response
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Merchant_Respond_Request'
  /withdraw/crypto-deposit-address:
    post:
      operationId: create-crypto-withdraw-deposit
      summary: Create Crypto Withdraw Deposit
      description: 'Create a crypto deposit session for a payout. Returns a deposit address where

        the merchant can send funds. Once funds are received via the deposit webhook,

        the payout is automatically initiated.'
      tags:
      - merchant
      parameters:
      - name: x-coinflow-auth-user-id
        in: header
        description: The external identifier of the end user - 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/CryptoWithdrawDepositResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCryptoWithdrawBody'
    get:
      operationId: get-supported-chains
      summary: Get Supported Chains
      description: Get the list of supported chains and tokens for crypto deposit withdrawals.
      tags:
      - merchant
      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/GetSupportedChainsResponse'
  /merchant/exports:
    post:
      operationId: create-export
      summary: Create Export
      description: Create a new export job
      tags:
      - merchant
      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/IExport'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExportRequest'
    get:
      operationId: list-exports
      summary: List Exports
      description: List all exports for the merchant
      tags:
      - merchant
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: number
          format: double
      - name: limit
        in: query
        required: false
        schema:
          type: number
          format: double
      - name: search
        in: query
        required: false
        schema:
          type: string
      - name: sortBy
        in: query
        required: false
        schema:
          type: string
      - name: sortDirection
        in: query
        required: false
        schema:
          type: number
          format: double
      - 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/IExport'
  /withdraw/crypto-deposit-address/deactivate:
    post:
      operationId: deactivate-passive-deposit-address
      summary: Deactivate Passive Deposit Address
      description: Deactivate (pause) a passive deposit address so it stops accepting new payments.
      tags:
      - merchant
      parameters:
      - name: x-coinflow-auth-user-id
        in: header
        description: The external identifier of the end user - 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/PassiveDepositAddressStatusResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PassiveDepositAddressBody'
  /merchant/exports/{exportId}:
    delete:
      operationId: delete-export
      summary: Delete Export
      description: Delete an export
      tags:
      - merchant
      parameters:
      - name: exportId
        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: Successful response
    get:
      operationId: get-export
      summary: Get Export
      description: Get a specific export by ID
      tags:
      - merchant
      parameters:
      - name: exportId
        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/IExport'
  /merchant:
    put:
      operationId: edit-merchant
      summary: Edit Merchant
      description: Edit the merchant details
      tags:
      - merchant
      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/IMerchant_string_'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                customerDefaultOverrideLimit:
                  $ref: '#/components/schemas/Cents'
                fraudEmails:
                  type: array
                  items:
                    type: string
                chargebackEmails:
                  type: array
                  items:
                    type: string
                billingEmails:
                  type: array
                  items:
                    type: string
                settlementAddresses:
                  $ref: '#/components/schemas/MerchantPutRequestBodyContentApplicationJsonSchemaSettlementAddresses'
                brand:
                  $ref: '#/components/schemas/MerchantBrandSettings'
                enforceJwt:
                  type: boolean
                cryptoPayinSettings:
                  $ref: '#/components/schemas/Pick_CryptoPayInSettings.customerEmailNotifications-or-merchantEmailNotifications_'
                achSettings:
                  $ref: '#/components/schemas/Pick_ACHSettings.customerEmailNotifications-or-merchantEmailNotifications_'
                cardSettings:
                  $ref: '#/components/schemas/Pick_CardSettings.customerEmailNotifications-or-merchantEmailNotifications_'
                webhookSettings:
                  $ref: '#/components/schemas/Pick_WebhookSettings.Exclude_keyofWebhookSettings.webhookUrls__'
                colors:
                  $ref: '#/components/schemas/MerchantTheme'
                password:
                  type: string
    get:
      operationId: get-merchant
      summary: Get Merchant
      description: Get the merchant
      tags:
      - merchant
      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/IMerchant_string_'
  /merchant/payments/{paymentId}/fail:
    put:
      operationId: fail-payment
      summary: Fail Payment
      description: '-- This method is for test environment only --

        Force an ACH, Wire, Iban, CashApp or PIX payment to fail'
      tags:
      - merchant
      parameters:
      - name: paymentId
        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: Successful response
  /merchant/chargebacks:
    get:
      operationId: get-all-chargebacks
      summary: Get all chargebacks
      tags:
      - merchant
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: number
          format: double
      - name: page
        in: query
        required: false
        schema:
          type: number
          format: double
      - name: status
        in: query
        required: false
        schema:
          type: string
      - name: search
        in: query
        required: false
        schema:
          type: string
      - name: sortBy
        in: query
        required: false
        schema:
          type: string
      - name: sortDirection
        in: query
        required: false
        schema:
          type: number
          format: double
      - name: responded
        in: query
        required: false
        schema:
          type: boolean
      - name: discrepancy
        in: query
        required: false
        schema:
          type: boolean
      - name: processor
        in: query
        required: false
        schema:
          type: string
      - name: protection
        in: query
        required: false
        schema:
          type: string
      - name: threeDSecure
        in: query
        required: false
        schema:
          type: string
      - name: merchantId
        in: query
        required: false
        schema:
          type: string
      - name: since
        in: query
        required: false
        schema:
          type: string
      - name: until
        in: query
        required: false
        schema:
          type: string
      - name: reasonCode
        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/AllChargebackResponse'
  /merchant/payments:
    get:
      operationId: get-all-payments
      summary: Get All Payments
      tags:
      - merchant
      parameters:
      - name: since
        in: query
        description: '- UTC epoch milliseconds of the earliest date to include in the results'
        required: false
        schema:
          type: string
      - name: until
        in: query
        description: '- UTC epoch milliseconds of the latest date to include in the results'
        required: false
        schema:
          type: string
      - name: page
        in: query
        description: '- Page number to return starting from 1. Must be used with limit param.'
        required: false
        schema:
          type: number
          format: double
      - name: limit
        in: query
        description: '- amount of records per page (def. 100). Must be used with page param.'
        required: false
        schema:
          type: number
          format: double
      - name: status
        in: query
        required: false
        schema:
          type: string
      - name: search
        in: query
        required: false
        schema:
          type: string
      - name: sortBy
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/MerchantPaymentsGetParametersSortBy'
      - name: sortDirection
        in: query
        required: false
        schema:
          type: number
          format: double
      - name: method
        in: query
        required: false
        schema:
          type: string
      - name: protection
        in: query
        required: false
        schema:
          type: string
      - name: merchantId
        in: query
        required: false
        schema:
          type: string
      - name: amount
        in: query
        required: false
        schema:
          type: string
      - name: authCode
        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/IPayment'
  /merchant/chargebacks/{paymentId}:
    get:
      operationId: get-chargeback
      summary: Get chargeback data
      description: Get information about a Chargeback for a payment
      tags:
      - merchant
      parameters:
      - name: paymentId
        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/Merchant_GetChargeback_Response_200'
  /merchant/chargebacks/{paymentId}/draft:
    get:
      operationId: get-chargeback-response-draft
      summary: Get Chargeback Response Draft
      tags:
      - merchant
      parameters:
      - name: paymentId
        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:
                type: string
    put:
      operationId: save-draft-and-notes
      summary: Save Chargeback Response Draft
      tags:
      - merchant
      parameters:
      - name: paymentId
        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: Successful response
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                notes:
                  type: string
                draft:
                  type: string
  /merchant/chargebacks/rate:
    get:
      operationId: get-chargeback-stats
      summary: Get chargeback stats for time frame
      tags:
      - merchant
      parameters:
      - name: since
        in: query
        description: -- YYYY-MM-DD
        required: false
        schema:
          type: string
      - name: until
        in: query
        description: -- YYYY-MM-DD
        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:
                $ref: '#/components/schemas/ChargebackStats'
  /merchant/withdraws/payout/balance:
    get:
      operationId: get-payout-balance
      summary: Get Coinflow Wallet Balance
      tags:
      - merchant
      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/Merchant_GetPayoutBalance_Response_200'
  /merchant/customers:
    get:
      operationId: get-customer-accounts
      summary: Get customer list
      description: List customers for a merchant
      tags:
      - merchant
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: number
          format: double
      - name: page
        in: query
        required: false
        schema:
          type: number
          format: double
      - name: blocked
        in: query
        required: false
        schema:
          type: string
      - name: search
        in: query
        required: false
        schema:
          type: string
      - name: sortBy
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/MerchantCustomersGetParametersSortBy'
      - name: sortDirection
        in: query
        required: false
        schema:
          type: number
          format: double
      - name: protection
        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/ICustomerWallet'
  /merchant/withdraws/payout/delegated/quote:
    post:
      operationId: get-delegated-payout-quote
      summary: Get Delegated Payout Quote
      description: 'Get a quote for a delegated payout including the fee breakdown.

        Shows the total amount that will be debited from the merchant''s wallet,

        the amount the user will receive, and the merchant fees.'
      tags:
      - merchant
      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/DelegatedPayoutQuote'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DelegatedPayoutQuoteArgs'
  /merchant/payments/enhanced/{paymentId}:
    get:
      operationId: get-enhanced-tx-information
      summary: Get Enhanced Transaction Information
      tags:
      - merchant
      parameters:
      - name: paymentId
        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/Merchant_GetEnhancedTxInformation_Response_200'
  /merchant/exports/{exportId}/download:
    get:
      operationId: get-export-download-url
      summary: Get Export Download URL
      description: Get a signed download URL for a completed export
      tags:
      - merchant
      parameters:
      - name: exportId
        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/ExportDownloadResponse'
  /merchant/credits/status/{jobId}:
    get:
      operationId: get-job-status
      summary: Get Job Status
      description: Get the status of a mint or burn job
      tags:
      - merchant
      parameters:
      - name: jobId
        in: path
        required: true
        schema:
          description: Any type
      - 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/JobStatusResponse'
  /merchant/v2:
    get:
      operationId: get-merchant-v-2
      summary: Get Merchant
      description: Get the merchant
      tags:
      - merchant
      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/Merchant_GetMerchantV2_Response_200'
  /merchant/payments/{paymentId}:
    get:
      operationId: get-payment-by-id
      summary: Get Payment By ID
      tags:
      - merchant
      parameters:
      - name: paymentId
        in: path
        description: '- ID of the payment to retrieve'
        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/IPayment'
  /merchant/webhooks:
    get:
      operationId: get-all-webhooks
      summary: Get Payment Webhook Activity
      tags:
      - merchant
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: number
          format: double
      - name: limit
        in: query
        required: false
        schema:
          type: number
          format: double
      - name: responseCode
        in: query
        required: false
        schema:
          type: string
      - name: search
        in: query
        description: Search by numeric responseCode
        required: false
        schema:
          type: string
      - name: eventType
        in: query
        required: false
        schema:
          type: string
      - name: merchantId
        in: query
        required: false
        schema:
          type: string
      - name: startDate
        in: query
        description: Filter by sentAt >= startDate (ISO 8601)
        required: false
        schema:
          type: string
      - name: endDate
        in: query
        description: Filter by sentAt <= endDate (ISO 8601)
        required: false
        schema:
          type: string
      - name: transactionId
        in: query
        description: Search by transaction Id
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: The API key of the merchant -

# --- truncated at 32 KB (307 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/coinflow/refs/heads/main/openapi/coinflow-merchant-api-openapi.yml