Skip to main content

​
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

ParameterValueDescription
EndpointPOST /api/v1/payinInitiate PayIn transaction
CurrencyCOPColombian Peso
Country CodeCOColombia
Auth RequiredYesToken-Top + Basic Auth

​
Request Parameters

​
Required Fields

FieldTypeDescriptionExample
referencestringUnique transaction identifier from your system"3cNPNGbX7meiMppXzVz7g781ysektqq5X"
amountintegerTransaction amount in cents (minor currency unit)5000 (= $50.00 COP)
currencystringThree-letter currency code (ISO 4217)"COP"
countrystringTwo-letter country code (ISO 3166-1 alpha-2)"CO"
payment_methodstringPayment method identifier"PSE", "EFECTY", "CARD", "BREB", "ALL_METHODS"
ipn_urlstringWebhook URL for transaction status updates"https://your-domain.com/webhook"
redirect_urlstringURL to redirect customer after payment"https://your-domain.com/payment/ok"
customer_dataobjectCustomer information object (see below)-

​
Customer Data Object

FieldTypeRequiredDescriptionExample
legal_docstring✅Customer’s legal document number"1234567890"
legal_doc_typestring✅Document types: CC, CE, PPN"CC"
phone_codestring✅Country calling code"57"
phone_numberstring✅Phone number without country code"3121234567"
emailstring✅Customer email address"[email protected]"
full_namestring✅Customer full name"John Doe"

​
Optional Fields

FieldTypeDescriptionDefault
descriptionstringTransaction description-
expiration_timeintegerPayment link expiration in minutes720 (12 hours)

​
Response Structure

​
Success Response

FieldTypeDescription
codestringResponse code ("01" = success)
statusstringTransaction status ("SUCCESS")
messagestringDescription of the response
dataobjectTransaction data object

​
Data Object

FieldTypeDescription
ticketstringUnique transaction identifier (TumiPay ID)
datestringTransaction timestamp (YYYY-MM-DD HH:MM:SS)
payment_urlstringSecure payment URL for customer redirect
transactionobjectTransaction details echo

​
Examples

​
Request

cURL
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": "[email protected]",
        "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.