Canopy Draws API

openapi: 3.2.0
info:
  title: Canopy Servicing Core Draws API
  description: 'Canopy allows you to easily manage credit, installment, or other more complex lending programs from a servicing and compliance perspective -

    whether newly launched or migrated from existing systems. using canopy, you can track balances and transactions for each customer of your product, both in real-time and historically.

    You can see how various policy and product changes would impact your customers, and readily generate compliance reports and minimize your risk with all real-time information always on hand.

    Canopy additionally surfaces information around all of your lending activity through its intuitive ui which provides a customer support interface as well as at-a-glance data needed for compliance and insights.

    Simply configure your product`s policies through our create product api endpoint, and then you can immediately begin adding customer accounts and relying on canopy for accurate servicing information.'
  contact:
    name: Canopy Support
    url: https://www.canopyservicing.com/contact
    email: support@canopyservicing.com
  version: 1.0.0
servers:
- url: Contact sales to enable your sandbox
  description: Your private sandbox environment
- url: https://demo-api.us.canopyservicing.com
  description: Demo environment
tags:
- name: Draws
  description: Manage draws on a line of credit for your customers in Canopy.
paths:
  /revolving/v1/accounts/{account_id}/line_of_credit/{line_of_credit_id}/draw:
    post:
      tags:
      - Draws
      summary: Create a draw for a line of credit
      description: 'Creates a new draw on a line of credit.


        Allows creation of a draw on an existing line of credit for a specified account, enabling users to request funds.


        The draw will decrease the available credit balance on the line of credit.'
      operationId: DrawCBV_create_draw_revolving_v1_accounts__account_id__line_of_credit__line_of_credit_id__draw_post
      security:
      - HTTPBearer: []
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
          title: Account Id
      - name: line_of_credit_id
        in: path
        required: true
        schema:
          type: string
          description: ID of the Line of Credit
          title: Line Of Credit Id
        description: ID of the Line of Credit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDrawSchema'
              description: Draw creation parameters
      responses:
        '201':
          description: Returns the created draw
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDrawResponse'
        '400':
          description: Your request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrBadRequestSchema'
        '404':
          description: Entity not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrNotFoundSchema'
        '409':
          description: Entity already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrConflictSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: A server error has occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrServerErrorSchema'
  /revolving/v1/accounts/{account_id}/line_of_credit/{line_of_credit_id}/backdated_action/draw:
    post:
      tags:
      - Draws
      summary: Create a backdated draw for a line of credit
      operationId: DrawCBV_create_backdated_draw_revolving_v1_accounts__account_id__line_of_credit__line_of_credit_id__backdated_action_draw_post
      security:
      - HTTPBearer: []
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
          title: Account Id
      - name: line_of_credit_id
        in: path
        required: true
        schema:
          type: string
          description: ID of the Line of Credit
          title: Line Of Credit Id
        description: ID of the Line of Credit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBackdatedDrawSchema'
              description: Draw creation parameters
      responses:
        '201':
          description: Returns the created draw
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDrawResponse'
        '400':
          description: Your request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrBadRequestSchema'
        '404':
          description: Entity not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrNotFoundSchema'
        '409':
          description: Entity already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrConflictSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: A server error has occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrServerErrorSchema'
  /revolving/v1/accounts/{account_id}/line_of_credit/{line_of_credit_id}/balance_transfer:
    post:
      tags:
      - Draws
      summary: Create a balance transfer for a line of credit
      operationId: DrawCBV_create_balance_transfer_revolving_v1_accounts__account_id__line_of_credit__line_of_credit_id__balance_transfer_post
      security:
      - HTTPBearer: []
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
          title: Account Id
      - name: line_of_credit_id
        in: path
        required: true
        schema:
          type: string
          description: ID of the Line of Credit
          title: Line Of Credit Id
        description: ID of the Line of Credit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBalanceTransferSchema'
              description: Balance transfer creation parameters
      responses:
        '201':
          description: Returns the created balance transfer draw and its fee
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateBalanceTransferResponse'
        '400':
          description: Your request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrBadRequestSchema'
        '404':
          description: Entity not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrNotFoundSchema'
        '409':
          description: Entity already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrConflictSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: A server error has occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrServerErrorSchema'
  /revolving/v1/accounts/{account_id}/line_of_credit/{line_of_credit_id}/draws/{draw_id}/capture:
    post:
      tags:
      - Draws
      summary: Capture a portion of an authorized draw
      description: 'Captures a specified amount from an authorized draw on a line of credit.

        This enables partial settlements against a single authorization, ideal for scenarios like

        e-commerce orders with multiple shipments. Use the ''final_capture'' flag to indicate the last capture.'
      operationId: DrawCBV_capture_draw_revolving_v1_accounts__account_id__line_of_credit__line_of_credit_id__draws__draw_id__capture_post
      security:
      - HTTPBearer: []
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
          title: Account Id
      - name: line_of_credit_id
        in: path
        required: true
        schema:
          type: string
          description: ID of the Line of Credit
          title: Line Of Credit Id
        description: ID of the Line of Credit
      - name: draw_id
        in: path
        required: true
        schema:
          type: string
          description: The unique identifier of the authorized draw to capture.
          title: Draw Id
        description: The unique identifier of the authorized draw to capture.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaptureDrawRequest'
              description: Capture draw parameters
      responses:
        '200':
          description: Returns details about the original draw and the capture
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaptureDrawResponse'
        '400':
          description: Your request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrBadRequestSchema'
        '404':
          description: Entity not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrNotFoundSchema'
        '409':
          description: Entity already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrConflictSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: A server error has occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrServerErrorSchema'
components:
  schemas:
    ErrBadRequestSchema:
      properties:
        message:
          type: string
          title: Message
          description: The error message
          examples:
          - Your request is invalid.
      type: object
      required:
      - message
      title: ErrBadRequestSchema
    CreateBalanceTransferResponse:
      properties:
        account_id:
          type: string
          title: Account Id
          description: The account id.
          hidden: false
        line_of_credit_id:
          type: string
          title: Line Of Credit Id
          description: The line of credit id.
          hidden: false
        effective_at:
          type: string
          title: Effective At
          description: The effective at date.
          hidden: false
        issued_at:
          type: string
          title: Issued At
          description: The issued at date.
          hidden: false
        status:
          anyOf:
          - additionalProperties: true
            type: object
          - items:
              additionalProperties: true
              type: object
            type: array
          - items: {}
            type: array
          title: Status
          description: The status of the entity.
          hidden: false
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - items:
              additionalProperties: true
              type: object
            type: array
          - items: {}
            type: array
          title: Metadata
          description: The metadata of the entity.
          hidden: false
        draw_id:
          type: string
          title: Draw Id
          description: The draw id.
          hidden: false
        card_id:
          type: string
          title: Card Id
          description: The card id associated with the draw.
        draw_type:
          type: string
          title: Draw Type
          description: The draw type.
          hidden: false
        original_amount_cents:
          type: integer
          title: Original Amount Cents
          description: The original amount of the draw.
          hidden: false
        balance_cents:
          type: integer
          title: Balance Cents
          description: The current balance of the draw.
          hidden: false
        interest_rate:
          type: number
          title: Interest Rate
          description: The annual interest rate as a whole number (e.g., 5.0 for 5%)
        promo_ids:
          items:
            type: string
          type: array
          title: Promo Ids
          description: IDs of the promotions applied to this transaction.
          hidden: false
        fee_id:
          type: string
          title: Fee Id
          description: ID of the balance transfer fee created alongside this draw
          hidden: false
      type: object
      required:
      - account_id
      - line_of_credit_id
      - effective_at
      - issued_at
      - draw_id
      - draw_type
      - original_amount_cents
      - balance_cents
      - promo_ids
      - fee_id
      title: CreateBalanceTransferResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    CaptureDrawResponse:
      properties:
        account_id:
          type: string
          title: Account Id
          description: The account id.
          hidden: false
        line_of_credit_id:
          type: string
          title: Line Of Credit Id
          description: The line of credit id.
          hidden: false
        effective_at:
          type: string
          title: Effective At
          description: The effective at date.
          hidden: false
        issued_at:
          type: string
          title: Issued At
          description: The issued at date.
          hidden: false
        status:
          anyOf:
          - additionalProperties: true
            type: object
          - items:
              additionalProperties: true
              type: object
            type: array
          - items: {}
            type: array
          title: Status
          description: The status of the entity.
          hidden: false
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - items:
              additionalProperties: true
              type: object
            type: array
          - items: {}
            type: array
          title: Metadata
          description: The metadata of the entity.
          hidden: false
        draw_id:
          type: string
          title: Draw Id
        capture_id:
          type: string
          title: Capture Id
        original_amount_cents:
          type: integer
          title: Original Amount Cents
        captured_amount_cents:
          type: integer
          title: Captured Amount Cents
        card_id:
          type: string
          title: Card Id
      type: object
      required:
      - account_id
      - line_of_credit_id
      - effective_at
      - issued_at
      - draw_id
      - capture_id
      - original_amount_cents
      - captured_amount_cents
      - card_id
      title: CaptureDrawResponse
    CreateBalanceTransferSchema:
      properties:
        draw_id:
          type: string
          title: Draw Id
          description: ID to associate with the draw. If not provided, Canopy will generate one.
          examples:
          - bt_draw_1
        card_id:
          type: string
          title: Card Id
          description: ID of the card associated with the balance transfer.
          examples:
          - card_1
        amount_cents:
          type: integer
          title: Amount Cents
          description: Amount to transfer in cents
          examples:
          - 50000
          hidden: false
        settlement_status:
          $ref: '#/components/schemas/TransactionStatusTypeStatuses'
          description: Settlement status of the draw.
          default: SETTLED
          examples:
          - SETTLED
          hidden: false
        interest_rate_percent:
          anyOf:
          - type: number
          - type: string
          title: Interest Rate Percent
          description: Annual interest rate for the draw as a whole number (e.g., 5.0 for 5%)
          examples:
          - 5
          hidden: false
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - items:
              additionalProperties: true
              type: object
            type: array
          - items: {}
            type: array
          maxLength: 100
          title: Metadata
          description: Metadata to associate with the draw
        fee:
          $ref: '#/components/schemas/BalanceTransferFeeInput'
          description: Fee to create atomically with the balance transfer
          hidden: false
      type: object
      required:
      - amount_cents
      - fee
      title: CreateBalanceTransferSchema
      description: Request schema for creating a balance transfer on a line of credit.
    CreateDrawSchema:
      properties:
        draw_id:
          type: string
          title: Draw Id
          description: The ID associated to be with the draw for future requests. If not provided on draw creation, Canopy will generate this field.
          examples:
          - draw_1
        card_id:
          type: string
          title: Card Id
          description: The ID associated to the card that is being used to create the draw.
          examples:
          - card_1
        amount_cents:
          type: integer
          title: Amount Cents
          description: The amount to draw from the line of credit
          examples:
          - 100000
          hidden: false
        draw_type:
          type: string
          title: Draw Type
          description: The type of draw to create
          examples:
          - SIMPLE_CHARGE
          hidden: false
        settlement_status:
          $ref: '#/components/schemas/TransactionStatusTypeStatuses'
          description: The settlement status of the draw, if not provided, the draw will be created with a SETTLED settlement status.
          default: SETTLED
          examples:
          - SETTLED
          hidden: false
        interest_rate_percent:
          anyOf:
          - type: number
          - type: string
          title: Interest Rate Percent
          description: The annual interest rate to apply to the draw as a percentage (e.g., 5.0 for 5%)
          examples:
          - 5
          hidden: false
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - items:
              additionalProperties: true
              type: object
            type: array
          - items: {}
            type: array
          maxLength: 100
          title: Metadata
          description: Metadata that can be associated with the draw
        override_draw_restrictions:
          $ref: '#/components/schemas/OverrideDrawRestrictions'
          description: Temporarily override draw restrictions for this request only.
        promo_id:
          type: string
          title: Promo Id
          description: The ID of the promo to apply to the draw. If not provided, eligible promos will be applied automatically to the draw.
          examples:
          - promo_1
      type: object
      required:
      - amount_cents
      - draw_type
      title: CreateDrawSchema
      description: Request schema for creating a draw on a line of credit.
    ErrNotFoundSchema:
      properties:
        message:
          type: string
          title: Message
          description: The error message
          examples:
          - Entity not found.
      type: object
      required:
      - message
      title: ErrNotFoundSchema
    ErrConflictSchema:
      properties:
        message:
          type: string
          title: Message
          description: The error message
          examples:
          - Entity already exists.
      type: object
      required:
      - message
      title: ErrConflictSchema
    CaptureDrawRequest:
      properties:
        captured_draw_id:
          type: string
          title: Captured Draw Id
          description: The ID of the captured draw.
          examples:
          - draw_123
        card_id:
          type: string
          title: Card Id
          description: The ID of the card that is being used to capture the draw.
          examples:
          - card_1
        amount_cents:
          type: integer
          title: Amount Cents
          description: The amount in cents to capture from the authorized draw.
          examples:
          - 100000
          hidden: false
        final_capture:
          type: boolean
          title: Final Capture
          description: Indicates whether this capture is the final one for the draw. If true, the original draw is settled after this capture, and no further captures are allowed. Any remaining authorized amount is voided rather than creating a new draw. If false, the original draw retains the remaining balance and a new draw is created for the captured amount.
          default: false
          examples:
          - true
          hidden: false
        metadata:
          additionalProperties: {}
          type: object
          title: Metadata
          description: Optional metadata providing context for this capture, such as the reason or related identifiers. Stored with the adjustment.
          examples:
          - order_id: ORD123
            reason: partial shipment
            shipment_id: SHIP001
      type: object
      required:
      - amount_cents
      title: CaptureDrawRequest
      description: Request schema for capturing a portion of an authorized draw in a multi-capture scenario.
    BalanceTransferFeeInput:
      properties:
        fee_id:
          type: string
          title: Fee Id
          description: ID for the fee. If not provided, Canopy will generate one.
          examples:
          - bt_fee_1
        amount_cents:
          type: integer
          title: Amount Cents
          description: Balance transfer fee amount in cents
          examples:
          - 2500
          hidden: false
      type: object
      required:
      - amount_cents
      title: BalanceTransferFeeInput
      description: Mandatory fee created atomically with the balance transfer draw.
    OverrideDrawRestrictions:
      properties:
        restrict_ltv_breach_draw_requests:
          type: boolean
          title: Restrict Ltv Breach Draw Requests
          description: Indicates whether the draw request should be restricted. If set to true, the request will be rejected if the resulting LTV exceeds the maximum allowed threshold.
          default: false
          examples:
          - true
          hidden: false
      type: object
      title: OverrideDrawRestrictions
      description: Schema for overriding draw restrictions on a line of credit.
    ErrServerErrorSchema:
      properties:
        message:
          type: string
          title: Message
          description: The error message
          examples:
          - A server error has occurred.
      type: object
      required:
      - message
      title: ErrServerErrorSchema
    CreateDrawResponse:
      properties:
        account_id:
          type: string
          title: Account Id
          description: The account id.
          hidden: false
        line_of_credit_id:
          type: string
          title: Line Of Credit Id
          description: The line of credit id.
          hidden: false
        effective_at:
          type: string
          title: Effective At
          description: The effective at date.
          hidden: false
        issued_at:
          type: string
          title: Issued At
          description: The issued at date.
          hidden: false
        status:
          anyOf:
          - additionalProperties: true
            type: object
          - items:
              additionalProperties: true
              type: object
            type: array
          - items: {}
            type: array
          title: Status
          description: The status of the entity.
          hidden: false
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - items:
              additionalProperties: true
              type: object
            type: array
          - items: {}
            type: array
          title: Metadata
          description: The metadata of the entity.
          hidden: false
        draw_id:
          type: string
          title: Draw Id
          description: The draw id.
          hidden: false
        card_id:
          type: string
          title: Card Id
          description: The card id associated with the draw.
        draw_type:
          type: string
          title: Draw Type
          description: The draw type.
          hidden: false
        original_amount_cents:
          type: integer
          title: Original Amount Cents
          description: The original amount of the draw.
          hidden: false
        balance_cents:
          type: integer
          title: Balance Cents
          description: The current balance of the draw.
          hidden: false
        interest_rate:
          type: number
          title: Interest Rate
          description: The annual interest rate as a whole number (e.g., 5.0 for 5%)
        promo_ids:
          items:
            type: string
          type: array
          title: Promo Ids
          description: IDs of the promotions applied to this transaction.
          hidden: false
      type: object
      required:
      - account_id
      - line_of_credit_id
      - effective_at
      - issued_at
      - draw_id
      - draw_type
      - original_amount_cents
      - balance_cents
      - promo_ids
      title: CreateDrawResponse
      description: Response schema for the create draw endpoint.
    CreateBackdatedDrawSchema:
      properties:
        draw_id:
          type: string
          title: Draw Id
          description: The ID associated to be with the draw for future requests. If not provided on draw creation, Canopy will generate this field.
          examples:
          - draw_1
        card_id:
          type: string
          title: Card Id
          description: The ID associated to the card that is being used to create the draw.
          examples:
          - card_1
        amount_cents:
          type: integer
          title: Amount Cents
          description: The amount to draw from the line of credit
          examples:
          - 100000
          hidden: false
        draw_type:
          type: string
          title: Draw Type
          description: The type of draw to create
          examples:
          - SIMPLE_CHARGE
          hidden: false
        settlement_status:
          $ref: '#/components/schemas/TransactionStatusTypeStatuses'
          description: The settlement status of the draw, if not provided, the draw will be created with a SETTLED settlement status.
          default: SETTLED
          examples:
          - SETTLED
          hidden: false
        interest_rate_percent:
          anyOf:
          - type: number
          - type: string
          title: Interest Rate Percent
          description: The annual interest rate to apply to the draw as a percentage (e.g., 5.0 for 5%)
          examples:
          - 5
          hidden: false
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - items:
              additionalProperties: true
              type: object
            type: array
          - items: {}
            type: array
          maxLength: 100
          title: Metadata
          description: Metadata that can be associated with the draw
        override_draw_restrictions:
          $ref: '#/components/schemas/OverrideDrawRestrictions'
          description: Temporarily override draw restrictions for this request only.
        promo_id:
          type: string
          title: Promo Id
          description: The ID of the promo to apply to the draw. If not provided, eligible promos will be applied automatically to the draw.
          examples:
          - promo_1
        backdated_to:
          type: string
          title: Backdated To
          description: The date and time to backdate the draw to on the line of credit
          examples:
          - '2019-10-15T23:59:59Z'
          hidden: false
      type: object
      required:
      - amount_cents
      - draw_type
      - backdated_to
      title: CreateBackdatedDrawSchema
      description: Request schema for creating a backdated draw on a line of credit.
    TransactionStatusTypeStatuses:
      type: string
      enum:
      - NONE
      - PENDING
      - FAILED
      - INVALID
      - VALID
      - REVERSED
      - DECLINED
      - SETTLED
      - PARTIALLY_SETTLED
      - IN_DISPUTE
      - LENDER_WON
      - LENDER_LOST
      - POURED
      - UNPOURED
      - REPOURED
      - AUTHORIZED
      - DEFERRED
      title: TransactionStatusTypeStatuses
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer