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

# Create Payin Request



## OpenAPI

````yaml POST /payinRequests
openapi: 3.0.0
info:
  title: Palomma API
  description: This API includes functionality of the Palomma API.
  version: 1.0.0
servers:
  - url: https://api.palomma.com/v0
    description: Production server
  - url: https://sandbox.api.palomma.com/v0
    description: Sandbox server
security:
  - BearerAuth: []
paths:
  /payinRequests:
    post:
      tags:
        - Payin Requests
      summary: Creates a new Payin Request
      operationId: createPayinRequest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - payinSourceId
                - amount
              properties:
                reference:
                  type: string
                  description: Reference sent in by merchant to identify Payin Request.
                payinSourceId:
                  type: string
                  description: ID indicating which Payment Source to debit from.
                amount:
                  type: number
                  description: >-
                    Amount to be paid in COP. Must be greater than $1.000. The
                    maxiumum is configured per merchant but defaults to
                    $2.000.000. Contact us if you need to increase this limit.
                targetMerchantAccountId:
                  description: >-
                    An optional account ID of the target merchant account for
                    this Payin Request.
                  type: string
      responses:
        '200':
          description: Payin Request created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayinRequest'
        '400':
          description: Bad Request - Invalid input provided
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Description of the error due to bad request.
        '401':
          description: >-
            Unauthorized - Authentication credentials were not provided or are
            invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Description of the error due to unauthorized access.
        '500':
          description: Internal Server Error - An error occurred on the server
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Description of the internal server error.
components:
  schemas:
    PayinRequest:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for this Payin Request.
          example: 01HPR83V7JBNJTKT303NTY3YGA
        reference:
          type: string
          description: Reference sent in by merchant to identify Payin Request.
        customerId:
          type: string
          description: >-
            Reference to customer who owns the Payin Source from which the Payin
            Request was created.
          example: 01HPR57X6QR5ZRKEEKBSDBW4RA
        customerDetails:
          $ref: '#/components/schemas/CustomerDetails'
          description: >-
            Details about the customer who owns the Payin Source from which the
            Payin Request was created.
        payinSourceId:
          type: string
          description: Reference to Payin Source from which the Payin Request was created.
          example: 01HPR7A40E44S0WDR189YXA8GH
        payinSourceDetails:
          $ref: '#/components/schemas/PayinSourceDetails'
          description: >-
            Details about the Payin Source from which the Payin Request was
            created.
        status:
          type: string
          enum:
            - processing
            - approved
            - partial
            - cancelled
          description: Status of the Payin Request.
          example: approved
        statusMessage:
          $ref: '#/components/schemas/StatusMessage'
        amount:
          type: number
          description: >-
            Amount to collect from the customer’s Payin Source. Must be an
            integer.
          example: 100000
        amountCollected:
          type: number
          description: >-
            Amount collected by Payin Request. Starts at 0 and changes on status
            change to "approved" or "partial".
          example: 100000
        fee:
          type: number
          description: >-
            Fee charged for the transaction. This fee will be subtracted from
            amountCollected at settlement time.
          example: 500
        targetMerchantAccountId:
          type: string
          description: >-
            Reference to Merchant Account. Safe to ignore if Merchant Accounts
            are not being used.
        createdAt:
          type: string
          format: date-time
          description: ISO string indicating when the payin request was created.
        updatedAt:
          type: string
          format: date-time
          description: ISO string indicating when the payin request was last updated.
    CustomerDetails:
      type: object
      properties:
        reference:
          type: string
          description: >-
            An optional reference provided by the merchant to identify the
            customer.
        name:
          type: string
          description: >-
            First and last name for a natural person, and company name for a
            juridical person.
          example: Pepito Perez
        documentType:
          type: string
          description: Colombian ID type for customer.
          enum:
            - cc
            - ce
            - nit
        documentNumber:
          type: string
          description: Colombian ID number for customer.
          example: '1037551022'
        email:
          type: string
          description: Customer’s email.
          format: email
          example: pepito@gmail.com
        phoneNumber:
          type: string
          description: Customer’s phone number.
          example: '3013111111'
    PayinSourceDetails:
      type: object
      properties:
        reference:
          type: string
          description: Reference sent in by merchant to identify Payin Source.
        description:
          type: string
          description: An extra metadata field that can be included for visibility.
        partialPayinsEnabled:
          type: boolean
          description: >-
            Only available for Bancolombia. Partial debit will be made if the
            account does not have sufficient funds to debit the total amount. By
            default, no partial debits will be made.
        type:
          type: string
          description: Type of Payin Source created.
          enum:
            - bankAccount
            - bancolombiaToken
            - nequiToken
    StatusMessage:
      type: string
      description: >-
        Additional detail on the status. Only present when status is
        "cancelled".
      enum:
        - AUTHENTICATION_FAILED
        - CUSTOMER_CANCELLATION
        - DECLINED_BY_BANK
        - EXPIRED
        - INVALID_ACCOUNT
        - NOT_ENOUGH_FUNDS
        - ERROR
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````