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

# PayIn API

> API for initiating PayIn transactions various payment methods.

# PayIn API

This API enables customer deposit transactions across supported countries. Payment method availability is region-specific:

* **Colombia**: `ALL_METHODS`, `PSE`, `TRANSFIYA`, `EFECTY`, `CASH`, `CARD`
* **Peru**: `BANK_TRANSFER`, `QR`, `CASH`, `CARD`, `PAGOEFECTIVO`
* **Mexico**: `ALL_METHODS`, `CARD`, `CASH`, `SPEI`, `OXXO`

For comprehensive country-specific configuration (supported document types, currencies, banks, and payment methods), refer to the [Colombia](/docs/co/introduction), [Peru](/docs/pe/introduction), and [Mexico](/docs/mx/introduction) documentation.

## Transaction Limits

**Amount limits:**

* **Minimum amount (PSE):** \$2,000
* **Minimum amount (Efecty):** \$10,000
* **Maximum amount:** \$2,000,000

To adjust these limits, please contact the Tumipay support team at [**soporte@tumipay.co**](mailto:soporte@tumipay.co).

## Transaction Flow

The PayIn process follows a clear sequence of interactions between different participants:

```mermaid theme={null}
sequenceDiagram
    participant M as Merchant
    participant T as TumiPay API
    participant P as Payment Provider
    participant B as Customer Bank
    participant C as Customer

    M->>T: 1. Create PayIn transaction
    T->>T: 2. Validate request & generate ticket
    T->>M: 3. Return payment_url & ticket
    M->>C: 4. Redirect customer to payment_url
    C->>P: 5. Complete payment form
    P->>B: 6. Process payment with bank
    B->>P: 7. Payment authorization response
    P->>T: 8. Notify payment status
    T->>T: 9. Update transaction status
    T->>M: 10. Send webhook with final status
    P->>C: 11. Redirect to success/failure page
```

## Card Payments (Colombia Only)

Card payment processing is currently available exclusively for Colombia (`country: "CO"`). Transactions follow the standard PayIn flow: initiate a transaction with `payment_method` set to `CARD`, redirect the customer to the `payment_url`, where they securely submit card details. The charge is processed asynchronously, and the final transaction status is delivered via webhook notification.

### 3D Secure

Some card transactions require 3D Secure (3DS) authentication. By having the 3DS authentication service active, your customers will be requested to complete an extra verification step (challenge) with the card issuer to finish the transaction. This challenge usually consists of an OTP sent by the bank to your customer’s e-mail address or telephone number.

To test this flow in the sandbox environment, use the card numbers marked with **Yes** in the `3DS challenge` column below. When the challenge screen appears, enter any six-digit code (for example `123456`) to continue.

### Sandbox test cards

Use the following card numbers in the sandbox environment. Use `123` as the CVV for all transactions:

| Card number         | 3DS challenge | Charge result |
| ------------------- | ------------- | ------------- |
| 4456 5400 0000 0063 | No            | Approved      |
| 4456 5433 7171 3314 | No            | Approved      |
| 4456 5419 8206 8615 | No            | Approved      |
| 4456 5412 4981 1088 | No            | Approved      |
| 4456 5300 0000 0031 | Yes           | Declined      |
| 4456 5300 0000 0106 | Yes           | Declined      |
| 4456 5365 8366 7765 | Yes           | Declined      |
| 4456 5365 0144 9767 | Yes           | Declined      |
| 4456 5327 0584 8821 | Yes           | Declined      |
| 4456 5280 8038 9860 | Yes           | Approved      |
| 4456 5292 6723 4200 | Yes           | Approved      |
| 4456 5291 6532 8302 | Yes           | Approved      |
| 4456 5248 6977 0255 | Yes           | Approved      |
| 4456 5233 4006 9956 | Yes           | Approved      |

## Endpoints

### POST Initiate a PayIn Transaction

<Card title="/api/v1/payin" icon="money-bill-transfer" iconType="solid">
  This endpoint enables deposit transactions using supported payment methods such as PSE and Efecty.
  Transactions are processed in real-time and support webhook notifications for status updates.
</Card>

#### Request Headers

<ParamField header="Token-Top" type="string" required>
  Authentication token
</ParamField>

<ParamField header="Authorization" type="string" required>
  Authorization key to access the resource
</ParamField>

#### Request Body

<ParamField body="reference" type="string" required>
  A unique identifier sent by the client to track the transaction
</ParamField>

<ParamField body="amount" type="integer" required>
  The total amount of the transaction
</ParamField>

<ParamField body="currency" type="string" required>
  The currency of the transaction. Use `COP` for Colombia, `PEN` for Peru, `MXN` for Mexico
</ParamField>

<ParamField body="country" type="string" required>
  Two-letter country code. Possible values: "CO", "PE", "MX"
</ParamField>

<ParamField body="payment_method" type="string" required>
  Specifies the payment method. See country-specific options:

  * [Colombia](/docs/co/introduction#payment-methods)
  * [Peru](/docs/pe/introduction#payment-methods)
  * [Mexico](/docs/mx/introduction#payment-methods)
</ParamField>

<ParamField body="description" type="string">
  Description of the transaction
</ParamField>

<ParamField body="redirect_url" type="string" required>
  The URL where the user will be redirected after completing the transaction
</ParamField>

<ParamField body="ipn_url" type="string" required>
  Webhook URL for transaction status updates
</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 types:

      * [Colombia](/docs/co/introduction#document-types)
      * [Peru](/docs/pe/introduction#document-types)
      * [Mexico](/docs/mx/introduction#document-types)
    </ParamField>

    <ParamField body="phone_code" type="string" required>
      Country code for the customer's phone number
    </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>

#### Response

<ResponseField name="code" type="string" required>
  Response code (see [Error Codes](#error-codes))
</ResponseField>

<ResponseField name="status" type="string" required>
  Transaction status (e.g., "SUCCESS")
</ResponseField>

<ResponseField name="message" type="string">
  Detailed message about the transaction status
</ResponseField>

<ResponseField name="data" type="object" required>
  <Expandable title="Transaction data object">
    <ResponseField name="ticket" type="string">
      Unique identifier for the transaction
    </ResponseField>

    <ResponseField name="date" type="string">
      The date and time when the transaction was processed
    </ResponseField>

    <ResponseField name="payment_url" type="string">
      URL for completing the payment transaction, generated by the payment provider
    </ResponseField>

    <ResponseField name="transaction" type="object">
      <Expandable title="Transaction details">
        <ResponseField name="reference" type="string">
          Client reference identifier
        </ResponseField>

        <ResponseField name="amount" type="integer">
          Transaction amount
        </ResponseField>

        <ResponseField name="currency" type="string">
          Currency code
        </ResponseField>

        <ResponseField name="payment_method" type="string">
          Selected payment method
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

#### Error Response

<ResponseField name="code" type="string">
  Error code (see [Error Codes](#error-codes))
</ResponseField>

<ResponseField name="status" type="string">
  Error status (e.g., "ERROR")
</ResponseField>

<ResponseField name="error" type="string">
  Type of validation error (e.g., "VALIDATION\_ERROR")
</ResponseField>

<ResponseField name="message" type="string">
  Details about the validation error
</ResponseField>

<RequestExample>
  <Tabs>
    <Tab title="cURL">
      ```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",
          "redirect_url": "https://www.tumipay.co/success",
          "ipn_url": "https://your-server.com/webhook",
          "expiration_time": 720,
          "customer_data": {
              "legal_doc": "1234567890",
              "legal_doc_type": "CC",
              "phone_code": "57",
              "phone_number": "3121234567",
              "email": "customer@example.com",
              "full_name": "John Doe"
          }
      }'
      ```
    </Tab>

    <Tab title="JavaScript">
      ```javascript theme={null}
      // Using fetch API
      const response = await fetch('https://api-empresas.staging.topup.com.co/production/api/v1/payin', {
        method: 'POST',
        headers: {
          'Token-Top': 'your_auth_token',
          'Authorization': 'Basic your_auth_key',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          reference: '3cNPNGbX7meiMppXzVz7g781ysektqq5X',
          amount: 5000,
          currency: 'COP',
          country: 'CO',
          payment_method: 'ALL_METHODS',
          description: 'Test PayIn',
          redirect_url: 'https://www.tumipay.co/success',
          ipn_url: 'https://your-server.com/webhook',
          expiration_time: 720,
          customer_data: {
            legal_doc: '1234567890',
            legal_doc_type: 'CC',
            phone_code: '57',
            phone_number: '3121234567',
            email: 'customer@example.com',
            full_name: 'John Doe'
          }
        })
      });
      const data = await response.json();
      ```
    </Tab>

    <Tab title="Python">
      ```python theme={null}
      import requests
      import json

      url = "https://api-empresas.staging.topup.com.co/production/api/v1/payin"

      headers = {
          'Token-Top': 'your_auth_token',
          'Authorization': 'Basic your_auth_key',
          'Content-Type': 'application/json'
      }

      payload = {
          "reference": "3cNPNGbX7meiMppXzVz7g781ysektqq5X",
          "amount": 5000,
          "currency": "COP",
          "country": "CO",
          "payment_method": "ALL_METHODS",
          "description": "Test PayIn",
          "redirect_url": "https://www.tumipay.co/success",
          "ipn_url": "https://your-server.com/webhook",
          "expiration_time": 720,
          "customer_data": {
              "legal_doc": "1234567890",
              "legal_doc_type": "CC",
              "phone_code": "57",
              "phone_number": "3121234567",
              "email": "customer@example.com",
              "full_name": "John Doe"
          }
      }

      response = requests.post(url, headers=headers, data=json.dumps(payload))
      result = response.json()
      ```
    </Tab>

    <Tab title="PHP">
      ```php theme={null}
      <?php
      $url = "https://api-empresas.staging.topup.com.co/production/api/v1/payin";

      $headers = array(
          'Token-Top: your_auth_token',
          'Authorization: Basic your_auth_key',
          'Content-Type: application/json'
      );

      $payload = array(
          "reference" => "3cNPNGbX7meiMppXzVz7g781ysektqq5X",
          "amount" => 5000,
          "currency" => "COP",
          "country" => "CO",
          "payment_method" => "ALL_METHODS",
          "description" => "Test PayIn",
          "redirect_url" => "https://www.tumipay.co/success",
          "ipn_url" => "https://your-server.com/webhook",
          "expiration_time" => 720,
          "customer_data" => array(
              "legal_doc" => "1234567890",
              "legal_doc_type" => "CC",
              "phone_code" => "57",
              "phone_number" => "3121234567",
              "email" => "customer@example.com",
              "full_name" => "John Doe"
          )
      );

      $ch = curl_init();
      curl_setopt($ch, CURLOPT_URL, $url);
      curl_setopt($ch, CURLOPT_POST, 1);
      curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
      curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

      $response = curl_exec($ch);
      curl_close($ch);

      $result = json_decode($response, true);
      ?>
      ```
    </Tab>
  </Tabs>
</RequestExample>

### Examples for Peru

#### BANK\_TRANSFER

*The payment link will show the available banks for the transfer.*

<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": "bank-transfer-ref-001",
      "amount": 5000,
      "currency": "PEN",
      "country": "PE",
      "payment_method": "BANK_TRANSFER",
      "description": "Bank transfer deposit",
      "redirect_url": "https://www.tumipay.pe/success",
      "ipn_url": "https://your-server.com/webhook",
      "expiration_time": 720,
      "customer_data": {
          "legal_doc": "12345678",
          "legal_doc_type": "DNI",
          "phone_code": "51",
          "phone_number": "987654321",
          "email": "customer@example.com",
          "full_name": "Maria Vargas"
      }
  }'
  ```
</RequestExample>

#### QR

*A QR code is generated for the customer to scan and complete the payment.*

<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": "qr-ref-001",
      "amount": 3000,
      "currency": "PEN",
      "country": "PE",
      "payment_method": "QR",
      "description": "QR payment",
      "redirect_url": "https://www.tumipay.pe/success",
      "ipn_url": "https://your-server.com/webhook",
      "expiration_time": 720,
      "customer_data": {
          "legal_doc": "87654321",
          "legal_doc_type": "DNI",
          "phone_code": "51",
          "phone_number": "912345678",
          "email": "customer@example.com",
          "full_name": "Carlos Rodriguez"
      }
  }'
  ```
</RequestExample>

#### PAGOEFECTIVO

*Generates a cash voucher (PagoEfectivo) for the customer to pay at authorized locations or via online banking. The payment link will show the code and instructions.*

<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": "pe-pagoefectivo-001",
      "amount": 2500,
      "currency": "PEN",
      "country": "PE",
      "payment_method": "PAGOEFECTIVO",
      "description": "PagoEfectivo deposit",
      "redirect_url": "https://www.tumipay.pe/success",
      "ipn_url": "https://your-server.com/webhook",
      "expiration_time": 720,
      "customer_data": {
          "legal_doc": "12345678",
          "legal_doc_type": "DNI",
          "phone_code": "51",
          "phone_number": "912345678",
          "email": "customer@example.com",
          "full_name": "Carlos Rodriguez"
      }
  }'
  ```
</RequestExample>

### Examples for Mexico

#### SPEI

*The payment link opens a SPEI transfer form where the customer authorizes an interbank transfer.*

<Note>
  For Mexico, SPEI can also run in **Direct Activation (Back to Back)** mode when enabled for your merchant account. In that flow, the response can return `clabe_number` and `expiration_date` for your own checkout experience. See [Mexico PayIn](/docs/mx/payin#direct-integrations-back-to-back).
</Note>

<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": "mx-spei-ref-001",
      "amount": 500.00,
      "currency": "MXN",
      "country": "MX",
      "payment_method": "SPEI",
      "description": "SPEI deposit",
      "redirect_url": "https://www.tumipay.mx/success",
      "ipn_url": "https://your-server.com/webhook",
      "expiration_time": 720,
      "customer_data": {
          "legal_doc": "CURP12345678901234",
          "legal_doc_type": "INE",
          "phone_code": "52",
          "phone_number": "5512345678",
          "email": "customer@example.com",
          "full_name": "Juan Pérez"
      }
  }'
  ```
</RequestExample>

#### OXXO

*Generates a cash voucher the customer can present and pay at any OXXO convenience store.*

<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": "mx-oxxo-ref-001",
      "amount": 200.00,
      "currency": "MXN",
      "country": "MX",
      "payment_method": "OXXO",
      "description": "OXXO cash deposit",
      "redirect_url": "https://www.tumipay.mx/success",
      "ipn_url": "https://your-server.com/webhook",
      "expiration_time": 720,
      "customer_data": {
          "legal_doc": "CURP12345678901234",
          "legal_doc_type": "INE",
          "phone_code": "52",
          "phone_number": "5512345678",
          "email": "customer@example.com",
          "full_name": "Juan Pérez"
      }
  }'
  ```
</RequestExample>

#### CASH

*Generates a cash payment reference for authorized collection points. `customer_address` is required for this method.*

<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": "mx-cash-ref-001",
      "amount": 300.00,
      "currency": "MXN",
      "country": "MX",
      "payment_method": "CASH",
      "description": "Cash deposit",
      "redirect_url": "https://www.tumipay.mx/success",
      "ipn_url": "https://your-server.com/webhook",
      "expiration_time": 720,
      "customer_data": {
          "legal_doc": "CURP12345678901234",
          "legal_doc_type": "INE",
          "phone_code": "52",
          "phone_number": "5512345678",
          "email": "customer@example.com",
          "full_name": "Juan Pérez",
          "customer_address": "Av. Insurgentes Sur 1602, Col. Crédito Constructor, CDMX"
      }
  }'
  ```
</RequestExample>

#### CARD (Mexico)

*The payment link opens a secure card form for credit and debit card payments.*

<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": "mx-card-ref-001",
      "amount": 750.00,
      "currency": "MXN",
      "country": "MX",
      "payment_method": "CARD",
      "description": "Card payment",
      "redirect_url": "https://www.tumipay.mx/success",
      "ipn_url": "https://your-server.com/webhook",
      "expiration_time": 720,
      "customer_data": {
          "legal_doc": "CURP12345678901234",
          "legal_doc_type": "INE",
          "phone_code": "52",
          "phone_number": "5512345678",
          "email": "customer@example.com",
          "full_name": "Juan Pérez"
      }
  }'
  ```
</RequestExample>

### Error Codes

| Code   | Meaning                               |
| ------ | ------------------------------------- |
| **01** | Operation successful                  |
| **00** | Validation error or processing failed |

### Examples by Payment Method

These examples use the same endpoint but change the `payment_method` field. The returned `payment_url` directs the customer to the appropriate interface for each method.

#### PSE

*The payment link opens the bank selection screen so the customer can authorize the transfer.*

<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": "pse-ref-001",
      "amount": 5000,
      "currency": "COP",
      "country": "CO",
      "payment_method": "PSE",
      "description": "PSE deposit",
      "redirect_url": "https://www.tumipay.co/success",
      "ipn_url": "https://your-server.com/webhook",
      "expiration_time": 720,
      "customer_data": {
          "legal_doc": "1234567890",
          "legal_doc_type": "CC",
          "phone_code": "57",
          "phone_number": "3121234567",
          "email": "customer@example.com",
          "full_name": "John Doe"
      }
  }'
  ```

  ```javascript theme={null}
  const response = await fetch('https://api-empresas.staging.topup.com.co/production/api/v1/payin', {
    method: 'POST',
    headers: {
      'Token-Top': 'your_auth_token',
      'Authorization': 'Basic your_auth_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      reference: 'pse-ref-001',
      amount: 5000,
      currency: 'COP',
      country: 'CO',
      payment_method: 'PSE',
      description: 'PSE deposit',
      redirect_url: 'https://www.tumipay.co/success',
      ipn_url: 'https://your-server.com/webhook',
      expiration_time: 720,
      customer_data: {
        legal_doc: '1234567890',
        legal_doc_type: 'CC',
        phone_code: '57',
        phone_number: '3121234567',
        email: 'customer@example.com',
        full_name: 'John Doe'
      }
    })
  });
  const data = await response.json();
  ```
</RequestExample>

#### EFECTY

*The payment link generates a cash voucher that must be presented at an Efecty location.*

<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": "efecty-ref-001",
      "amount": 20000,
      "currency": "COP",
      "country": "CO",
      "payment_method": "EFECTY",
      "description": "Cash deposit",
      "redirect_url": "https://www.tumipay.co/success",
      "ipn_url": "https://your-server.com/webhook",
      "expiration_time": 720,
      "customer_data": {
          "legal_doc": "1234567890",
          "legal_doc_type": "CC",
          "phone_code": "57",
          "phone_number": "3121234567",
          "email": "customer@example.com",
          "full_name": "John Doe"
      }
  }'
  ```

  ```javascript theme={null}
  const response = await fetch('https://api-empresas.staging.topup.com.co/production/api/v1/payin', {
    method: 'POST',
    headers: {
      'Token-Top': 'your_auth_token',
      'Authorization': 'Basic your_auth_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      reference: 'efecty-ref-001',
      amount: 20000,
      currency: 'COP',
      country: 'CO',
      payment_method: 'EFECTY',
      description: 'Cash deposit',
      redirect_url: 'https://www.tumipay.co/success',
      ipn_url: 'https://your-server.com/webhook',
      expiration_time: 720,
      customer_data: {
        legal_doc: '1234567890',
        legal_doc_type: 'CC',
        phone_code: '57',
        phone_number: '3121234567',
        email: 'customer@example.com',
        full_name: 'John Doe'
      }
    })
  });
  const data = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "code": "01",
    "status": "SUCCESS",
    "message": "Operation successful",
    "data": {
      "ticket": "efecty-ticket-id",
      "date": "2024-12-27 14:35:00",
      "payment_url": "https://example.com/payment/efecty",
      "transaction": {
        "reference": "efecty-ref-001",
        "amount": 20000,
        "currency": "COP",
        "payment_method": "EFECTY"
      }
    }
  }
  ```
</ResponseExample>

#### CARD

*`The payment link opens a secure card form. The webhook payload includes a top_card object with details of the card used.`*

<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": "card-ref-001",
      "amount": 5000,
      "currency": "COP",
      "country": "CO",
      "payment_method": "CARD",
      "description": "Card payment",
      "redirect_url": "https://www.tumipay.co/success",
      "ipn_url": "https://your-server.com/webhook",
      "expiration_time": 720,
      "customer_data": {
          "legal_doc": "1234567890",
          "legal_doc_type": "CC",
          "phone_code": "57",
          "phone_number": "3121234567",
          "email": "customer@example.com",
          "full_name": "John Doe"
      }
  }'
  ```

  ```javascript theme={null}
  const response = await fetch('https://api-empresas.staging.topup.com.co/production/api/v1/payin', {
    method: 'POST',
    headers: {
      'Token-Top': 'your_auth_token',
      'Authorization': 'Basic your_auth_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      reference: 'card-ref-001',
      amount: 5000,
      currency: 'COP',
      country: 'CO',
      payment_method: 'CARD',
      description: 'Card payment',
      redirect_url: 'https://www.tumipay.co/success',
      ipn_url: 'https://your-server.com/webhook',
      expiration_time: 720,
      customer_data: {
        legal_doc: '1234567890',
        legal_doc_type: 'CC',
        phone_code: '57',
        phone_number: '3121234567',
        email: 'customer@example.com',
        full_name: 'John Doe'
      }
    })
  });
  const data = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "code": "01",
    "status": "SUCCESS",
    "message": "Operation successful",
    "data": {
      "ticket": "card-ticket-id",
      "date": "2024-12-27 14:35:00",
      "payment_url": "https://example.com/payment/card",
      "transaction": {
        "reference": "card-ref-001",
        "amount": 5000,
        "currency": "COP",
        "payment_method": "CARD"
      }
    }
  }
  ```
</ResponseExample>

## Response Examples

<ResponseExample>
  ```json theme={null}
  {
    "code": "01",
    "status": "SUCCESS",
    "message": "Operation successful",
    "data": {
      "ticket": "1fb500ad-feb4-409d-95ba-c10b708abf05",
      "date": "2024-12-27 14:35:00",
      "payment_url": "https://example.com/payment/12345",
      "transaction": {
        "reference": "3cNPNGbX7meiMppXzVz7g781ysektqq5X",
        "amount": 5000,
        "currency": "COP",
        "payment_method": "PSE"
      }
    }
  }
  ```

  ```json Error Response theme={null}
  {
    "code": "00",
    "status": "ERROR",
    "error": "VALIDATION_ERROR",
    "message": "The payment method is invalid."
  }
  ```
</ResponseExample>