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

For comprehensive country-specific configuration (supported document types, currencies, banks, and payment methods), refer to the Colombia and Peru 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 [email protected].

Transaction Flow

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

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

/api/v1/payin

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.

Request Headers

Token-Top

string

required

Authentication token

Authorization

string

required

Authorization key to access the resource

Request Body

reference

string

required

A unique identifier sent by the client to track the transaction

amount

integer

required

The total amount of the transaction

currency

string

required

The currency of the transaction. Use COP for Colombia, PEN for Peru

country

string

required

Two-letter country code. Possible values: “CO”, “PE”, “MX”

payment_method

string

required

Specifies the payment method. See country-specific options:

description

string

Description of the transaction

redirect_url

string

required

The URL where the user will be redirected after completing the transaction

ipn_url

string

required

Webhook URL for transaction status updates

customer_data

object

required

Show Customer data object

legal_doc

string

required

The customer’s legal document number

legal_doc_type

string

required

The type of legal document provided. See country-specific types:

phone_code

string

required

Country code for the customer’s phone number

phone_number

string

required

The customer’s phone number, excluding the country code

string

required

The customer’s email address

full_name

string

required

The customer’s full name as it appears on official documents

Response

code

string

required

Response code (see Error Codes)

status

string

required

Transaction status (e.g., “SUCCESS”)

message

string

Detailed message about the transaction status

data

object

required

Show Transaction data object

ticket

string

Unique identifier for the transaction

date

string

The date and time when the transaction was processed

payment_url

string

URL for completing the payment transaction, generated by the payment provider

transaction

object

Show Transaction details

reference

string

Client reference identifier

amount

integer

Transaction amount

currency

string

Currency code

payment_method

string

Selected payment method

Error Response

code

string

Error code (see Error Codes)

status

string

Error status (e.g., “ERROR”)

error

string

Type of validation error (e.g., “VALIDATION_ERROR”)

message

string

Details about the validation error

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": "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": "[email protected]",
        "full_name": "John Doe"
    }
}'

JavaScript

// Using fetch API
const response = await fetch('https://api-empresas.staging.tumipay.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: '[email protected]',
      full_name: 'John Doe'
    }
  })
});
const data = await response.json();

Python

import requests
import json

url = "https://api-empresas.staging.tumipay.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": "[email protected]",
        "full_name": "John Doe"
    }
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
result = response.json()

PHP

<?php
$url = "https://api-empresas.staging.tumipay.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" => "[email protected]",
        "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);
?>

Examples for Peru

BANK_TRANSFER

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

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": "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": "[email protected]",
        "full_name": "Maria Vargas"
    }
}'

QR

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

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": "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": "[email protected]",
        "full_name": "Carlos Rodriguez"
    }
}'

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.

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": "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": "[email protected]",
        "full_name": "Carlos Rodriguez"
    }
}'

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.

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": "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": "[email protected]",
        "full_name": "John Doe"
    }
}'

EFECTY

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

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": "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": "[email protected]",
        "full_name": "John Doe"
    }
}'

{
  "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"
    }
  }
}

CARD

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

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": "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": "[email protected]",
        "full_name": "John Doe"
    }
}'

{
  "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"
    }
  }
}

Response Examples

{
  "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"
    }
  }
}

Getting Started

Merchant API

PayIn API

PayOut API

Integration

PayIn API

PayIn API

Transaction Limits

Transaction Flow

Card Payments (Colombia Only)

3D Secure

Sandbox test cards

Endpoints

POST Initiate a PayIn Transaction

/api/v1/payin

Request Headers

Request Body

Response

Error Response

Examples for Peru

BANK_TRANSFER

QR

PAGOEFECTIVO

Error Codes

Examples by Payment Method

PSE

EFECTY

CARD

Response Examples

Getting Started

Merchant API

PayIn API

PayOut API

Integration

​PayIn API

​Transaction Limits

​Transaction Flow

​Card Payments (Colombia Only)

​3D Secure

​Sandbox test cards

​Endpoints

​POST Initiate a PayIn Transaction

/api/v1/payin

​Request Headers

​Request Body

​Response

​Error Response

​Examples for Peru

​BANK_TRANSFER

​QR

​PAGOEFECTIVO

​Error Codes

​Examples by Payment Method

​PSE

​EFECTY

​CARD

​Response Examples

PayIn API

Transaction Limits

Transaction Flow

Card Payments (Colombia Only)

3D Secure

Sandbox test cards

Endpoints

POST Initiate a PayIn Transaction

Request Headers

Request Body

Response

Error Response

Examples for Peru

BANK_TRANSFER

QR

PAGOEFECTIVO

Error Codes

Examples by Payment Method

PSE

EFECTY

CARD

Response Examples