POST Initiate PayIn Transaction

Initialize a new PayIn transaction for payment processing

POST /payin

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",
    "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/success"
}'

{
    "code": "01",
    "status": "SUCCESS",
    "message": "Operacion exitosa",
    "data": {
        "ticket": "8BNsCFva1NKPqy2",
        "date": "2025-10-15 17:58:36",
        "payment_url": "https://link.staging.tumipay.co/payments/main?s=8BNsCFva1NKPqy2",
        "transaction": {
            "reference": "13cNPNGbX7meiMppXzVz7g781ysektqq5X",
            "amount": 5000,
            "currency": "PEN",
            "payment_method": "ALL_METHODS",
            "redirect_url": "https://your-domain.com/payment/success",
            "ipn_url": "https://your-domain.com/webhook",
            "description": "Test PayIn"
        }
    }
}

Initialize a new PayIn transaction for payment processing.

This endpoint allows you to create a new payment request that your customers can pay through various payment methods.

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",
    "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/success"
}'

{
    "code": "01",
    "status": "SUCCESS",
    "message": "Operacion exitosa",
    "data": {
        "ticket": "8BNsCFva1NKPqy2",
        "date": "2025-10-15 17:58:36",
        "payment_url": "https://link.staging.tumipay.co/payments/main?s=8BNsCFva1NKPqy2",
        "transaction": {
            "reference": "13cNPNGbX7meiMppXzVz7g781ysektqq5X",
            "amount": 5000,
            "currency": "PEN",
            "payment_method": "ALL_METHODS",
            "redirect_url": "https://your-domain.com/payment/success",
            "ipn_url": "https://your-domain.com/webhook",
            "description": "Test PayIn"
        }
    }
}

Required Headers

Token-Top · string · required

Your merchant authentication token

Authorization · string · required

Basic authentication key

Content-Type · string · required

Must be “application/json”

Request Body Parameters

reference · string · required

Your unique transaction reference

amount · number · required

Transaction amount in the specified currency code.

currency · string · required

Three-letter currency code following the ISO 4217 standard (e.g., COP, PEN).

payment_method · string · required

Payment method. See Country-Specific Information for available payment methods.

description · string · required

Transaction description or purpose.

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 Information for available document types.

phone_code · string · required

Country code for the customer’s phone number (e.g., 57, 51)

phone_number · string · required

The customer’s phone number, excluding the country code

email · string · required

The customer’s email address

full_name · string · required

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

expiration_time · integer

Payment link expiration time in minutes

ipn_url · string · required

URL for receiving webhook notifications

redirect_url · string · required

URL to redirect after payment completion

Response

ticket · string

Unique transaction identifier (UUID v4)

reference · string

Your provided transaction reference (must be unique)

status · string

Initial transaction status (will be PENDING)

payment_url · string

URL to redirect the customer for payment

expiration · string

Payment link expiration timestamp (UTC)

Authorizations

Token-Top · string · header · required

Merchant authentication token

Authorization · string · header · required

Basic authentication with username and password

Body

application/json

reference · string · required

Your unique transaction reference

amount · number · required

Transaction amount (in cents/minor currency unit)

currency · string · required

Three-letter currency code (ISO 4217)

Example:

"COP"

payment_method · enum<string> · required

Payment method to be used. Availability varies by country.

Available options: ALL_METHODS, PSE, EFECTY, TRANSFIYA, CARD, BANK_TRANSFER, QR, PAGOEFECTIVO

ipn_url · string<uri> · required

URL for receiving webhook notifications

redirect_url · string<uri> · required

URL to redirect after payment completion

country · string · required

Two-letter country code (ISO 3166-1 alpha-2). Possible values: CO, PE, MX

Example:

"CO"

description · string

Transaction description

customer_data · object

Show child attributes

metadata · object

Custom metadata managed entirely by your implementation. Include any fields you require.

expiration_time · integer

Payment link expiration time in minutes

Response

200

application/json

Successful response

ticket · string

Unique transaction identifier

reference · string

Your provided transaction reference

status · enum<string>

Initial transaction status

Available options: PENDING

payment_url · string<uri>

URL to redirect the customer for payment

expiration · string<date-time>

Payment link expiration timestamp (UTC)