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

# Create Cash Payout

> Create cash payment, using the created quote

Initiates a cash payout to a fiat beneficiary.


## OpenAPI

````yaml POST /ledger/cash-payments
openapi: 3.0.3
info:
  version: 3.0.2
  title: Onboard External API Gateway
  description: >-
    **Introduction**

    API Gateway for Onboard


    This specification describes API endpoints that are available to the public
    internet via the API gateway. The different endpoints require different
    authentication schemes, see documentation for what applies to the operation
    you want to access.


    **Errors**

    Uses conventional HTTP response codes to indicate success or failure. In

    general:
     
    - `2xx` status codes indicate success. Codes in the

    - `4xx` range

    indicate a client error (e.g. required parameters, failed request etc.).

    - `5xx` status codes indicate a server error occurred.
  contact:
    name: Nestcoin TechOps
    email: techops@nestcoin.com
  license:
    name: UNLICENSED
servers:
  - url: https://external.dev.onboardpay.co
    description: Gateway for external API on staging environment.
security: []
tags:
  - name: users-onboardapi
    description: Endpoints available to for merchants liquidity automation
  - name: users-users
    description: User related endpoints
  - name: users-partners
    description: Partner related endpoints
  - name: users-admin
    description: Back office related endpoints
  - name: users-user2fa
    description: User 2fa related endpoints
  - name: users-usernotifications
    description: User notifications related endpoints
  - name: users-merchantnetwork
    description: Merchant network endpoints
  - name: users-userauth
    description: Authentication endpoints
  - name: users-userservice
    description: Service endpoints
  - name: users-webhook
    description: webhook endpoints
  - name: users-config
    description: Configuration Endpoints
paths:
  /ledger/cash-payments:
    post:
      tags:
        - ledger-payments
      summary: Create cash payment
      description: Create cash payment, using the created quote
      operationId: createCashPayment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCashPaymentRequest'
      responses:
        '200':
          description: Cash payment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferResponse'
        '400':
          $ref: '#/components/responses/LedgerSvcInvalidRequest'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
      security:
        - HMACAuth: []
components:
  schemas:
    CreateCashPaymentRequest:
      type: object
      description: >-
        Details required to create a cash payment. The amount and currency must
        align with an existing quote.
      required:
        - quoteId
        - accountId
        - amount
        - beneficiaryId
        - reference
        - paymentReason
      properties:
        quoteId:
          type: string
          format: uuid
          description: >-
            Identifier of an existing cash payment quote, retrieved from the
            cash payment quote endpoint.
        accountId:
          type: string
          format: uuid
          description: >-
            Account to debit for this payment. Can be the main account ID or a
            sub-account ID.
        reference:
          type: string
          description: Alpha-numeric transfer reference, unique for this transfer.
          example: CTR123456
          pattern: ^[a-zA-Z0-9_-]{8,48}$
          minLength: 8
          maxLength: 48
        amount:
          type: number
          minimum: 0
          exclusiveMinimum: true
        unitCurrency:
          type: string
          description: |
            Should be same as one of payout or account currencies in the quote. 
            Defaults to account currency if not provided.
        beneficiaryId:
          type: string
          format: uuid
          description: >-
            Identifier of an existing beneficiary to whom the transfer will be
            made.
        paymentReason:
          type: string
          description: >-
            Reason for the payment, to be provided at the time of transfer
            creation.
        narration:
          type: string
          description: Notes to be included in the transfer.
      x-source-svc: ledger
    TransferResponse:
      type: object
      additionalProperties: false
      description: The payment initiation response
      required:
        - id
        - status
        - awaiting2fA
      properties:
        id:
          type: string
          example: P12005E1DV
        status:
          $ref: '#/components/schemas/TransactionStatus'
        awaiting2fA:
          type: boolean
          default: false
          description: >-
            Indicates if transfer is awaiting 2FA confirmation. This applies
            mostly to transaction initiated via dashboard
        twoFaMethod:
          type: array
          description: List of 2fa enabled
          items:
            $ref: '#/components/schemas/User2FAMethod'
      x-source-svc: ledger
    TransactionStatus:
      type: string
      description: >
        Status of the transaction, indicating its current state in the
        processing lifecycle.

        - PENDING: The transaction has been created but not yet processed.

        - IN_PROGRESS: The transaction is currently being processed.

        - FAILED: The transaction processing has failed.

        - SUCCESS: The transaction has been successfully processed.
      enum:
        - PENDING
        - IN_PROGRESS
        - FAILED
        - SUCCESS
      x-source-svc: ledger
    User2FAMethod:
      type: string
      enum:
        - AUTHENTICATOR_APP
        - EMAIL
        - SMS
      x-source-svc: ledger
    ErrorMessageDto:
      description: >-
        Default error object for services. This gives consistent error object
        that all services may use.
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Error code
          example: UNKNOWN_ERROR
        message:
          type: string
          description: Descriptive error message
          example: Request could not be completed due to an error
        data:
          type: object
          description: Additional data for this error message.
          additionalProperties: true
          properties: {}
      x-common-model: ErrorMessageDto
  responses:
    LedgerSvcInvalidRequest:
      description: Request could not be validated
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageDto'
          example:
            code: BAD_REQUEST
            message: Request could not be validated.
    LedgerSvcUnauthorized:
      description: Client is not authorized to make request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageDto'
          example:
            code: UNAUTHORIZED
            message: Either client security header is missing or it is not valid.
  securitySchemes:
    HMACAuth:
      type: apiKey
      name: x-api-key
      in: header
      description: |-
        Requires authentication via API key and HMAC signature.
          * `x-api-key`: Your API key generated from your Onboard Business dashboard.
          * `x-timestamp`:  Unix epoch timestamp (seconds) used in signature, allowed skew is 30 seconds
          * `x-signature`: SHA256 HMAC HEX signature calculated over  `t={x-timestamp}&{requestBody}` using your API Secret.

````