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

# POST Initiate PayIn Transaction

> Initialize a new PayIn transaction for payment processing

Initialize a new PayIn transaction for payment processing.

This endpoint allows you to create a new payment request that your customers can pay through various payment methods.

<RequestExample>
  ```bash theme={null}
  curl --request POST 'https://api-empresas.staging.topup.com.co/production/api/v1/payin' \
  --header 'Token-Top: your_auth_token' \
  --header 'Authorization: Basic your_auth_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "reference": "3cNPNGbX7meiMppXzVz7g781ysektqq5X",
      "amount": 5000,
      "currency": "COP",
      "country": "CO",
      "payment_method": "ALL_METHODS",
      "description": "Test PayIn",
      "customer_data": {
          "legal_doc": "1234567890",
          "legal_doc_type": "CC",
          "phone_code": "57",
          "phone_number": "3121234567",
          "email": "customer@example.com",
          "full_name": "John Doe"
      },
      "expiration_time": 720,
      "ipn_url": "https://your-domain.com/webhook",
      "redirect_url": "https://your-domain.com/payment/success"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
      "code": "01",
      "status": "SUCCESS",
      "message": "Operacion exitosa",
      "data": {
          "ticket": "8BNsCFva1NKPqy2",
          "date": "2025-10-15 17:58:36",
          "payment_url": "https://link.staging.topup.com.co/payments/main?s=8BNsCFva1NKPqy2",
          "transaction": {
              "reference": "13cNPNGbX7meiMppXzVz7g781ysektqq5X",
              "amount": 5000,
              "currency": "PEN",
              "payment_method": "ALL_METHODS",
              "redirect_url": "https://your-domain.com/payment/success",
              "ipn_url": "https://your-domain.com/webhook",
              "description": "Test PayIn"
          }
      }
  }
  ```
</ResponseExample>

## Required Headers

<ParamField header="Token-Top" type="string" required>
  Your merchant authentication token
</ParamField>

<ParamField header="Authorization" type="string" required>
  Basic authentication key
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be "application/json"
</ParamField>

## Request Body Parameters

<ParamField body="reference" type="string" required>
  Your unique transaction reference
</ParamField>

<ParamField body="amount" type="number" required>
  Transaction amount in the specified currency code.
</ParamField>

<ParamField body="currency" type="string" required>
  Three-letter currency code following the ISO 4217 standard (e.g., <code>COP</code>, <code>PEN</code>).
</ParamField>

<ParamField body="payment_method" type="string" required>
  Payment method. See [Country-Specific Information](/docs/introduction#country-specific-information) for available payment methods.
</ParamField>

<ParamField body="description" type="string" required>
  Transaction description or purpose.
</ParamField>

<ParamField body="customer_data" type="object" required>
  <Expandable title="Customer data object">
    <ParamField body="legal_doc" type="string" required>
      The customer's legal document number
    </ParamField>

    <ParamField body="legal_doc_type" type="string" required>
      The type of legal document provided. See [Country-Specific Information](/docs/introduction#country-specific-information) for available document types.
    </ParamField>

    <ParamField body="phone_code" type="string" required>
      Country code for the customer's phone number (e.g., <code>57</code>, <code>51</code>)
    </ParamField>

    <ParamField body="phone_number" type="string" required>
      The customer's phone number, excluding the country code
    </ParamField>

    <ParamField body="email" type="string" required>
      The customer's email address
    </ParamField>

    <ParamField body="full_name" type="string" required>
      The customer's full name as it appears on official documents
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="expiration_time" type="integer">
  Payment link expiration time in minutes
</ParamField>

<ParamField body="ipn_url" type="string" required>
  URL for receiving webhook notifications
</ParamField>

<ParamField body="redirect_url" type="string" required>
  URL to redirect after payment completion
</ParamField>

## Response

<ResponseField name="ticket" type="string">
  Unique transaction identifier (UUID v4)
</ResponseField>

<ResponseField name="reference" type="string">
  Your provided transaction reference (must be unique)
</ResponseField>

<ResponseField name="status" type="string">
  Initial transaction status (will be <code>PENDING</code>)
</ResponseField>

<ResponseField name="payment_url" type="string">
  URL to redirect the customer for payment
</ResponseField>

<ResponseField name="expiration" type="string">
  Payment link expiration timestamp (UTC)
</ResponseField>


## OpenAPI

````yaml post /payin
openapi: 3.0.0
info:
  title: PayIn API
  version: 1.0.0
  description: API for payment processing operations
servers:
  - url: https://api-empresas.staging.topup.com.co/production/api/v1
    description: Staging server
security: []
paths:
  /payin:
    post:
      summary: Initiate PayIn Transaction
      description: Initialize a new PayIn transaction for payment processing
      operationId: initiatePayIn
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - reference
                - amount
                - currency
                - payment_method
                - ipn_url
                - redirect_url
                - country
              properties:
                reference:
                  type: string
                  description: Your unique transaction reference
                amount:
                  type: number
                  description: Transaction amount (in cents/minor currency unit)
                currency:
                  type: string
                  description: Three-letter currency code (ISO 4217)
                  example: COP
                payment_method:
                  type: string
                  enum:
                    - ALL_METHODS
                    - PSE
                    - EFECTY
                    - TRANSFIYA
                    - CARD
                    - BANK_TRANSFER
                    - QR
                    - PAGOEFECTIVO
                  description: Payment method to be used. Availability varies by country.
                description:
                  type: string
                  description: Transaction description
                customer_data:
                  type: object
                  required:
                    - legal_doc
                    - legal_doc_type
                    - phone_code
                    - phone_number
                    - email
                    - full_name
                  properties:
                    legal_doc:
                      type: string
                      description: The customer's legal document number.
                    legal_doc_type:
                      type: string
                      enum:
                        - CC
                        - CE
                        - PPN
                        - DNI
                        - RUC
                      description: >-
                        The type of legal document provided. Varies by country:
                        Colombia (CC, CE, PPN), Peru (DNI, RUC, CE, PPN)
                    phone_code:
                      type: string
                      description: Country code for the customer's phone number.
                    phone_number:
                      type: string
                      description: The customer's phone number, excluding the country code.
                    email:
                      type: string
                      format: email
                      description: The customer's email address
                    full_name:
                      type: string
                      description: >-
                        The customer's full name as it appears on official
                        documents.
                metadata:
                  type: object
                  description: >-
                    Custom metadata managed entirely by your implementation.
                    Include any fields you require.
                  additionalProperties: true
                expiration_time:
                  type: integer
                  description: Payment link expiration time in minutes
                ipn_url:
                  type: string
                  format: uri
                  description: URL for receiving webhook notifications
                redirect_url:
                  type: string
                  format: uri
                  description: URL to redirect after payment completion
                country:
                  type: string
                  description: >-
                    Two-letter country code (ISO 3166-1 alpha-2). Possible
                    values: CO, PE, MX
                  example: CO
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ticket:
                    type: string
                    description: Unique transaction identifier
                  reference:
                    type: string
                    description: Your provided transaction reference
                  status:
                    type: string
                    enum:
                      - PENDING
                    description: Initial transaction status
                  payment_url:
                    type: string
                    format: uri
                    description: URL to redirect the customer for payment
                  expiration:
                    type: string
                    format: date-time
                    description: Payment link expiration timestamp (UTC)
        '400':
          description: Invalid request parameters
        '401':
          description: Unauthorized
        '422':
          description: Validation error
      security:
        - Token-Top: []
          BasicAuth: []
components:
  securitySchemes:
    Token-Top:
      type: apiKey
      name: Token-Top
      in: header
      description: Merchant authentication token
    BasicAuth:
      type: http
      scheme: basic
      description: Basic authentication with username and password

````