> ## 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 (v1 — deprecated)

> Legacy PayIn endpoint. Always returns a hosted payment_url. Deprecated — use POST /api/v2/payin for new integrations.

<Warning>
  **This endpoint is deprecated.** Use [`POST /api/v2/payin`](/api-reference/payin/post-initiate-transaction) for all new integrations. PayIn v2 supports checkout, direct, and hybrid payment experiences without separate backoffice configuration.
</Warning>

Initialize a PayIn transaction using the legacy **v1** API.

This version always returns a hosted **`payment_url`** for the customer to complete payment. Direct and hybrid flows (PSE without redirect, EFECTY instructions, BREB keys, etc.) are available only in [PayIn v2](/api-reference/payin).

<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": "3cNPNGbX7meiMppXzVz7g781ysektqq5X",
              "amount": 5000,
              "currency": "COP",
              "payment_method": "ALL_METHODS",
              "redirect_url": "https://your-domain.com/payment/success",
              "ipn_url": "https://your-domain.com/webhook",
              "description": "Test PayIn"
          }
      }
  }
  ```
</ResponseExample>

## Migration to v2

| v1 behavior                               | v2 equivalent                                                                           |
| ----------------------------------------- | --------------------------------------------------------------------------------------- |
| Hosted checkout (`payment_url`)           | Same — use v2 without extra fields                                                      |
| Back-to-back PSE (backoffice flag)        | Send `customer_data.bank` + `customer_data.person_type` with `payment_method: "PSE"`    |
| Back-to-back SPEI (Mexico, merchant flag) | Send `payment_method: "SPEI"` — v2 returns hybrid `payment_url` + `payment_information` |
| Separate B2B configuration                | Not required in v2                                                                      |

See [PayIn API (v2)](/api-reference/payin) and [Colombia PayIn](/docs/co/payin) for method-specific v2 examples.

## 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.
</ParamField>

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

<ParamField body="country" type="string" required>
  Two-letter country code (ISO 3166-1 alpha-2), e.g. `CO`, `PE`, `MX`.
</ParamField>

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

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

<ParamField body="customer_data" type="object" required>
  Customer identification and contact details (`legal_doc`, `legal_doc_type`, `phone_code`, `phone_number`, `email`, `full_name`).
</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
</ResponseField>

<ResponseField name="payment_url" type="string">
  Hosted checkout URL to redirect the customer
</ResponseField>

<ResponseField name="transaction" type="object">
  Echo of request metadata (reference, amount, currency, payment\_method, urls)
</ResponseField>


## OpenAPI

````yaml post /api/v1/payin
openapi: 3.0.0
info:
  title: PayIn API
  version: 2.0.0
  description: >-
    PayIn v2 is the recommended API. v1 is deprecated — migrate to POST
    /api/v2/payin for checkout, direct, and hybrid payment experiences.
servers:
  - url: https://api-empresas.staging.topup.com.co/production
    description: Staging server
security: []
paths:
  /api/v1/payin:
    post:
      tags:
        - PayIn
      summary: Initiate PayIn Transaction (v1 — deprecated)
      description: >-
        Legacy PayIn endpoint. Always returns a hosted payment_url. Deprecated —
        use POST /api/v2/payin for new integrations.
      operationId: initiatePayInV1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - reference
                - amount
                - currency
                - country
                - payment_method
                - description
                - customer_data
                - ipn_url
                - redirect_url
              properties:
                reference:
                  type: string
                amount:
                  type: number
                currency:
                  type: string
                  example: COP
                country:
                  type: string
                  example: CO
                payment_method:
                  type: string
                description:
                  type: string
                customer_data:
                  type: object
                  required:
                    - legal_doc
                    - legal_doc_type
                    - phone_code
                    - phone_number
                    - email
                    - full_name
                  properties:
                    legal_doc:
                      type: string
                    legal_doc_type:
                      type: string
                    phone_code:
                      type: string
                    phone_number:
                      type: string
                    email:
                      type: string
                      format: email
                    full_name:
                      type: string
                expiration_time:
                  type: integer
                ipn_url:
                  type: string
                  format: uri
                redirect_url:
                  type: string
                  format: uri
      responses:
        '200':
          description: Transaction created
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      ticket:
                        type: string
                      date:
                        type: string
                      payment_url:
                        type: string
                      transaction:
                        type: object
        '422':
          description: Validation error
      deprecated: true
      security:
        - Token-Top: []
          BasicAuth: []
components:
  securitySchemes:
    Token-Top:
      type: apiKey
      name: Token-Top
      in: header
    BasicAuth:
      type: http
      scheme: basic

````