> ## 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 > Country-specific information for PayIn transactions in Colombia. # Colombia - PayIn ## Overview The PayIn API for Colombia enables customer deposit transactions through multiple payment methods including **PSE** (online bank transfers), **Efecty** (cash payments), and **Card** payments. Transactions are processed in real-time with webhook notifications for status updates. ### Key Features * **Multiple Payment Methods**: `PSE`, `EFECTY`, `CARD`, `BREB`, `ALL_METHODS` * **Currency**: Colombian Peso (`COP`) * **Real-time Processing**: Immediate transaction validation and processing * **Webhook Notifications**: Asynchronous status updates via IPN * **Secure Redirect Flow**: Customer completes payment on secure hosted page ### Quick Reference | Parameter | Value | Description | | ----------------- | -------------------- | -------------------------- | | **Endpoint** | `POST /api/v1/payin` | Initiate PayIn transaction | | **Currency** | `COP` | Colombian Peso | | **Country Code** | `CO` | Colombia | | **Auth Required** | Yes | Token-Top + Basic Auth | *** ## Request Parameters ### Required Fields | Field | Type | Description | Example | | ---------------- | ------- | ------------------------------------------------- | -------------------------------------------------------- | | `reference` | string | Unique transaction identifier from your system | `"3cNPNGbX7meiMppXzVz7g781ysektqq5X"` | | `amount` | integer | Transaction amount in cents (minor currency unit) | `5000` (= \$50.00 COP) | | `currency` | string | Three-letter currency code (ISO 4217) | `"COP"` | | `country` | string | Two-letter country code (ISO 3166-1 alpha-2) | `"CO"` | | `payment_method` | string | Payment method identifier | `"PSE"`, `"EFECTY"`, `"CARD"`, `"BREB"`, `"ALL_METHODS"` | | `ipn_url` | string | Webhook URL for transaction status updates | `"https://your-domain.com/webhook"` | | `redirect_url` | string | URL to redirect customer after payment | `"https://your-domain.com/payment/ok"` | | `customer_data` | object | Customer information object (see below) | - | ### Customer Data Object | Field | Type | Required | Description | Example | | ---------------- | ------ | -------- | --------------------------------- | ----------------------- | | `legal_doc` | string | ✅ | Customer's legal document number | `"1234567890"` | | `legal_doc_type` | string | ✅ | Document types: `CC`, `CE`, `PPN` | `"CC"` | | `phone_code` | string | ✅ | Country calling code | `"57"` | | `phone_number` | string | ✅ | Phone number without country code | `"3121234567"` | | `email` | string | ✅ | Customer email address | `"johndoe@example.com"` | | `full_name` | string | ✅ | Customer full name | `"John Doe"` | ### Optional Fields | Field | Type | Description | Default | | ----------------- | ------- | ---------------------------------- | ---------------- | | `description` | string | Transaction description | - | | `expiration_time` | integer | Payment link expiration in minutes | `720` (12 hours) | *** ## Response Structure ### Success Response | Field | Type | Description | | --------- | ------ | -------------------------------- | | `code` | string | Response code (`"01"` = success) | | `status` | string | Transaction status (`"SUCCESS"`) | | `message` | string | Description of the response | | `data` | object | Transaction data object | ### Data Object | Field | Type | Description | | ------------- | ------ | ------------------------------------------- | | `ticket` | string | Unique transaction identifier (TumiPay ID) | | `date` | string | Transaction timestamp (YYYY-MM-DD HH:MM:SS) | | `payment_url` | string | Secure payment URL for customer redirect | | `transaction` | object | Transaction details echo | *** ## Examples ### Request ```bash cURL 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": "BREB", "description": "Test PayIn", "customer_data": { "legal_doc": "1234567890", "legal_doc_type": "CC", "phone_code": "57", "phone_number": "3121234567", "email": "johndoe@example.com", "full_name": "John Doe" }, "expiration_time": 720, "ipn_url": "https://your-domain.com/webhook", "redirect_url": "https://your-domain.com/payment/ok" }' ``` ```bash cURL 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": "johndoe@example.com", "full_name": "John Doe" }, "expiration_time": 720, "ipn_url": "https://your-domain.com/webhook", "redirect_url": "https://your-domain.com/payment/ok" }' ``` ```rust Rust theme={null} use reqwest::Client; use serde_json::json; async fn make_payin_request() -> Result<(), reqwest::Error> { let client = Client::new(); let response = client.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") .json(&json!({ "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": "johndoe@example.com", "full_name": "John Doe" }, "expiration_time": 720, "ipn_url": "https://your-domain.com/webhook", "redirect_url": "https://your-domain.com/payment/ok" })) .send() .await?; let response_json: serde_json::Value = response.json().await?; println!("{:#?}", response_json); Ok(()) } ``` ```typescript TypeScript theme={null} import axios from 'axios'; const makePayinRequest = async () => { try { const response = await axios.post('https://api-empresas.staging.topup.com.co/production/api/v1/payin', { 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: 'johndoe@example.com', full_name: 'John Doe' }, expiration_time: 720, ipn_url: 'https://your-domain.com/webhook', redirect_url: 'https://your-domain.com/payment/ok' }, { headers: { 'Token-Top': 'your_auth_token', 'Authorization': 'Basic your_auth_key', 'Content-Type': 'application/json' } }); console.log(response.data); } catch (error) { console.error(error); } }; makePayinRequest(); ``` ```php PHP theme={null} 'https://api-empresas.staging.topup.com.co/production/api/v1/payin', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "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": "johndoe@example.com", "full_name": "John Doe" }, "expiration_time": 720, "ipn_url": "https://your-domain.com/webhook", "redirect_url": "https://your-domain.com/payment/ok" }', CURLOPT_HTTPHEADER => array( 'Token-Top: your_auth_token', 'Authorization: Basic your_auth_key', 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` ```java Java theme={null} import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.net.URI; import java.io.IOException; public class PayinRequest { public static void main(String[] args) throws IOException, InterruptedException { HttpClient client = HttpClient.newHttpClient(); String json = "{ \\"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\\": \\"johndoe@example.com\\", \\"full_name\\": \\"John Doe\\" }, \\"expiration_time\\": 720, \\"ipn_url\\": \\"https://your-domain.com/webhook\\", \\"redirect_url\\": \\"https://your-domain.com/payment/ok\\" }"; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("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") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); } } ``` ```go Go theme={null} package main import ( "fmt" "net/http" "io/ioutil" "strings" ) func main() { url := "https://api-empresas.staging.topup.com.co/production/api/v1/payin" method := "POST" payload := strings.NewReader(`{ "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": "johndoe@example.com", "full_name": "John Doe" }, "expiration_time": 720, "ipn_url": "https://your-domain.com/webhook", "redirect_url": "https://your-domain.com/payment/ok" }`) client := &http.Client {} req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("Token-Top", "your_auth_token") req.Header.Add("Authorization", "Basic your_auth_key") req.Header.Add("Content-Type", "application/json") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` ### Response ```json theme={null} { "code": "01", "status": "SUCCESS", "message": "Operacion exitosa", "data": { "ticket": "dAF1RNdSFn936Yi", "date": "2025-10-15 15:44:57", "payment_url": "https://link.staging.topup.com.co/payments/main?s=dAF1RNdSFn936Yi", "transaction": { "reference": "3cNPNGbX7meiMppXzVz7g781ysektqq5X", "amount": 5000, "currency": "COP", "payment_method": "ALL_METHODS", "redirect_url": "https://your-domain.com/payment/ok", "ipn_url": "https://your-domain.com/webhook", "description": "Test PayIn" } } } ``` *** # Advanced Integration For direct PayIn integration without redirecting users to checkout, see [Back to Back Integration](/docs/co/back-to-back).