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	"[e-mail]"
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

cURL

shellscript

curl --request POST 'https://api-empresas.staging.tumipay.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": "[e-mail]",
        "full_name": "John Doe"
    },
    "expiration_time": 720,
    "ipn_url": "https://your-domain.com/webhook",
    "redirect_url": "https://your-domain.com/payment/ok"
}'

Response

{
  "code": "01",
  "status": "SUCCESS",
  "message": "Operacion exitosa",
  "data": {
      "ticket": "dAF1RNdSFn936Yi",
      "date": "2025-10-15 15:44:57",
      "payment_url": "https://link.staging.tumipay.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.