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

# Create a BRE-B payout

> Requires an approved customer. Creates a Bre-B external account and
verifies name + key before returning the deposit transaction.
`409 destination_mismatch` if verify does not match. `409 needs_kyc` if KYC is incomplete.




## OpenAPI

````yaml /openapi.yaml post /api/integrations/breb/payouts
openapi: 3.1.0
info:
  title: COP By Integrations API
  version: 0.1.0
  description: |
    Non-custodial Celo API for partners. Prepare swaps and BRE-B COP payouts;
    the user signs from their wallet. Confirm with the transaction hash.
servers:
  - url: http://localhost:3000
    description: Local Next.js app
  - url: https://app.copby.co
    description: Production (replace if your origin differs)
security:
  - bearerAuth: []
tags:
  - name: BRE-B
    description: Quote, KYC, and COP payouts via Bridge Bre-B
  - name: Swaps
    description: Prepare and confirm onchain COPm swaps
  - name: Webhooks
    description: Bridge callbacks. Not authenticated with a partner key.
paths:
  /api/integrations/breb/payouts:
    post:
      tags:
        - BRE-B
      summary: Create a BRE-B payout
      description: >
        Requires an approved customer. Creates a Bre-B external account and

        verifies name + key before returning the deposit transaction.

        `409 destination_mismatch` if verify does not match. `409 needs_kyc` if
        KYC is incomplete.
      operationId: createBrebPayout
      parameters:
        - name: Idempotency-Key
          in: header
          schema:
            type: string
          description: Replays the same payout when reused by this integration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePayoutRequest'
            example:
              userAddress: '0x2222222222222222222222222222222222222222'
              fromToken: USDC
              destinationCop: '10000'
              breBKey: '31234567890'
              accountOwnerName: Ana Pérez
      responses:
        '200':
          description: Prepared payout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payout'
        '400':
          $ref: '#/components/responses/BrebError'
        '409':
          $ref: '#/components/responses/BrebError'
components:
  schemas:
    CreatePayoutRequest:
      type: object
      required:
        - userAddress
        - destinationCop
        - breBKey
        - accountOwnerName
      properties:
        userAddress:
          $ref: '#/components/schemas/Address'
        fromToken:
          type: string
          enum:
            - USDC
            - COPm
          default: USDC
        destinationCop:
          type: string
          example: '10000'
        breBKey:
          type: string
        accountOwnerName:
          type: string
        quoteId:
          type: string
    Payout:
      type: object
      properties:
        payoutId:
          type: string
        status:
          type: string
        fromToken:
          type: string
        sourceAmount:
          type: string
        fees:
          type: array
          items:
            $ref: '#/components/schemas/FeeLeg'
        quote:
          type: object
          properties:
            display:
              type:
                - string
                - 'null'
            effectiveUsdCop:
              type:
                - string
                - 'null'
        receipt:
          $ref: '#/components/schemas/PayoutReceipt'
        deposit:
          type: object
          properties:
            chain:
              type: string
            currency:
              type: string
            address:
              type: string
            amount:
              type: string
        transaction:
          $ref: '#/components/schemas/PreparedTx'
        feeTransaction:
          $ref: '#/components/schemas/PreparedTx'
        destinationPreview:
          type: object
          properties:
            accountOwnerName:
              type: string
            bankName:
              type:
                - string
                - 'null'
            documentLast4:
              type:
                - string
                - 'null'
    Address:
      type: string
      pattern: ^0x[a-fA-F0-9]{40}$
      example: '0x2222222222222222222222222222222222222222'
    FeeLeg:
      type: object
      properties:
        code:
          type: string
          enum:
            - swap
            - bridge_fx
            - bridge
            - copby
        amountUsd:
          type: string
        to:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - quoted
            - verified
            - pending
    PayoutReceipt:
      type: object
      description: >
        Consumer receipt (REQ-INT-RCPT-01). Fees are included in
        `exchangeRate.effectiveUsdCop`.

        Use `feesItemized` only for partner backoffice / disputes.
      properties:
        title:
          type: string
          example: Retiro Bre-B
        status:
          type: string
        completedAt:
          type:
            - string
            - 'null'
        transactionType:
          type: string
          enum:
            - withdrawal
        payoutId:
          type: string
        breBKey:
          type:
            - string
            - 'null'
          description: Masked key (last4), e.g. ···3143
        breBKeyLast4:
          type:
            - string
            - 'null'
        beneficiaryName:
          type:
            - string
            - 'null'
        totalPaid:
          type: object
          properties:
            amount:
              type: string
            currency:
              type: string
              enum:
                - USD
        exchangeRate:
          type: object
          properties:
            display:
              type:
                - string
                - 'null'
              example: 1 USD = 3000 COP
            effectiveUsdCop:
              type:
                - string
                - 'null'
            sellRateUsdCop:
              type:
                - string
                - 'null'
              description: Wholesale Bridge rate (ops); hide on consumer UI
        commission:
          type: object
          properties:
            mode:
              type: string
              enum:
                - included_in_rate
            displayAmount:
              type: string
              example: '0'
            displayCurrency:
              type: string
              enum:
                - COP
                - USD
            note:
              type: string
        totalReceived:
          type: object
          properties:
            amount:
              type: string
            currency:
              type: string
              enum:
                - COP
        feesItemized:
          type: array
          items:
            $ref: '#/components/schemas/FeeLeg'
    PreparedTx:
      type: object
      properties:
        approvalTarget:
          type:
            - string
            - 'null'
        to:
          type: string
        data:
          type: string
        value:
          type: string
          example: '0'
    ErrorBody:
      type: object
      properties:
        error:
          type: string
        errorCode:
          type: string
          enum:
            - below_minimum
            - needs_kyc
            - destination_mismatch
            - requote
            - tx_hash_reused
            - otp_invalid
            - mercado_cerrado
            - invalid_webhook_signature
  responses:
    BrebError:
      description: API error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Integration API key. Send as `Bearer copby_live_pk_…`.

````