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

# Create Payment

> Initiate a new payment transaction. This endpoint creates a payment quote that must be confirmed using the complete endpoint.

Initiate a new payment transaction. This endpoint creates a payment quote that must be confirmed using the [Confirm Payment](/api-reference/payments/confirm-payment) endpoint.

## Overview

This endpoint starts a payment transaction by creating a payment quote. The quote includes fees, exchange rates, and total amount to collect. After reviewing the quote, you must call the confirm endpoint to execute the payment.

<Warning>
  Payments require a two-step process: first initiate to get a quote, then complete to execute the payment. Quotes expire after 5 minutes.
</Warning>

## Payment Flow

1. **Initiate Payment** - Call this endpoint with payment details to get a quote
2. **Review Quote** - Check the fees, exchange rates, and total amount
3. **Confirm Payment** - Use the `quote_id` and `reference` from the response to complete the payment

<Tip>
  Use the `Idempotency-Key` header to prevent duplicate payments if you need to retry the request.
</Tip>


## OpenAPI

````yaml POST /payments/initiate
openapi: 3.0.0
info:
  title: Pooler Developer API
  description: >-
    Comprehensive API documentation for Pooler payment and financial services
    platform
  version: 1.0.0
servers:
  - url: https://api.usepooler.com
    description: Production server
  - url: https://sandbox.usepooler.com
    description: Sandbox server
security:
  - bearerAuth: []
paths:
  /payments/initiate:
    post:
      tags:
        - Payments
      summary: Create Payment
      description: >-
        Initiate a new payment transaction. This endpoint creates a payment
        quote that must be confirmed using the complete endpoint.
      operationId: createPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequest'
      responses:
        '200':
          description: Payment initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
components:
  schemas:
    CreatePaymentRequest:
      type: object
      required:
        - amount
        - currency
        - recipient_id
      properties:
        amount:
          type: number
          description: Payment amount
        currency:
          type: string
          description: Currency code (e.g., NGN, USD)
        description:
          type: string
          description: Payment description
        reference:
          type: string
          description: Unique reference for the payment
        recipient_id:
          type: string
          format: uuid
          description: ID of the payment recipient
        transaction_type:
          type: string
          description: Type of transaction (e.g., inter)
        transaction_category:
          type: string
          description: Transaction category (e.g., transfer)
        transaction_tags:
          type: string
          description: Comma-separated tags for the transaction
        transaction_notes:
          type: string
          description: Additional notes for the transaction
        channel:
          type: string
          description: Payment channel (e.g., bank)
        sub_type:
          type: string
          description: Transaction sub-type (e.g., transfer)
    PaymentResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        stan:
          type: string
          format: uuid
        data:
          $ref: '#/components/schemas/Payment'
    Payment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        reference:
          type: string
        status:
          type: string
          enum:
            - pending
            - completed
            - failed
        amount:
          type: string
        currency:
          type: string
        description:
          type: string
        type:
          type: string
        sub_type:
          type: string
        category:
          type: string
        transaction_date:
          type: string
          format: date-time
        tags:
          type: string
        is_reversed:
          type: boolean
        is_completed:
          type: boolean
        channel:
          type: string
        notes:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer token authentication. Include your API key in the Authorization
        header as: Bearer {your_api_key}

````