# TumiPay Documentation

> APIs and guides for processing payments and payouts with TumiPay.

TumiPay is a payment processing platform that enables businesses to handle payment collections (PayIn) and disbursements (PayOut) across Latin American countries. Currently supporting Colombia and Peru, with comprehensive APIs for financial transactions.

## Project Overview

TumiPay provides three main API services:
1. **PayIn API**: Process payment collections through various payment methods (PSE, cards, bank transfers, cash, QR codes)
2. **PayOut API**: Handle disbursements to bank accounts and digital wallets
3. **Merchant API**: Retrieve merchant balance and search transaction history

## Authentication & Authorization

All API requests require dual authentication:
- **Basic Authentication**: Base64-encoded username:password in Authorization header
- **Token-Top Header**: Merchant-specific authentication token

Example:
```
Authorization: Basic base64(username:password)
Token-Top: your_access_token
Content-Type: application/json
```

Credentials are obtained by contacting: it@tumipay.co, tecnologia@tumipay.co, or soporte@tumipay.co

## Environments

### Staging (Sandbox)
Base URL: https://api-empresas.staging.topup.com.co/production/api
- No real monetary transactions
- Testing environment for integration
- Use approved@tumipay.co or tumipay@tumipay.co for approved test transactions
- Any other email simulates rejected transactions
- For PayOut testing, first create a successful PayIn to add funds to balance

### Production
Contact TumiPay support after successful sandbox testing to receive production credentials and endpoint.

## Country-Specific Information

### Colombia (CO)
Currency: COP

**PayIn Methods:**
- ALL_METHODS: All available payment methods
- PSE: Online bank transfers
- TRANSFIYA: Real-time bank transfers
- EFECTY: Cash payments at Efecty locations
- CASH: Cash payments
- CARD: Credit and debit card payments (Colombia only, supports 3D Secure)

**PayOut Methods:**
- BANK_TRANSFER: Traditional bank transfer
- BREB: Interoperable real-time transfers

**Document Types (PayIn):** CC (Cédula de Ciudadanía), CE (Cédula de Extranjería), PPN (Pasaporte)
**Document Types (PayOut):** CC, CE, PPN, NIT (Número de Identificación Tributaria)
**Account Types:** AHORRO (Savings), CORRIENTE (Checking)

**Supported Banks:** Nequi, Daviplata, Bancolombia, Davivienda, Banco Bogotá, Banco Popular, BBVA, and 40+ other banks and digital wallets.

### Peru (PE)
Currency: PEN

**PayIn Methods:**
- ALL_METHODS: All available payment methods
- BANK_TRANSFER: Bank transfers
- QR: QR code payments
- PAGOEFECTIVO: Cash voucher with code and outlets
- CASH: Standard cash payments
- CARD: Credit and debit card payments

**PayOut Methods:**
- BANK_TRANSFER: Bank transfers

**Document Types:** DNI (Documento Nacional de Identidad), RUC (Registro Único de Contribuyentes), CE (Carné de Extranjería), PPN (Pasaporte)
**Account Types:** AHORRO (Savings), CORRIENTE (Checking), WALLET (Digital wallet)

**Supported Banks:** BBVA, BCP, Interbank, Scotiabank, Yape, Plin, BIM, and 40+ other banks and financial institutions.

## API Endpoints

### PayIn API
POST /api/v1/payin
Creates a payment collection transaction. Returns a payment_url for customer to complete payment.

**Required Fields:**
- reference (string): Unique merchant reference
- amount (integer): Transaction amount
- currency (string): COP or PEN
- country (string): CO or PE
- payment_method (string): See country-specific methods
- redirect_url (string): URL to redirect customer after payment
- ipn_url (string): Webhook URL for status updates
- customer_data (object): legal_doc, legal_doc_type, phone_code, phone_number, email, full_name

**Transaction Limits:**
- Minimum (PSE): $2,000
- Minimum (Efecty): $10,000
- Maximum: $2,000,000

**Response:** Returns ticket, payment_url, and transaction details

### PayOut API
POST /api/v1/payout
Creates a disbursement transaction to bank accounts or wallets.

**Required Fields:**
- payment_method (string): See country-specific methods
- reference (string): Unique merchant reference
- amount (integer): Amount to transfer
- currency (string): COP or PEN
- country (string): CO or PE
- ipn_url (string): Webhook URL for status updates
- customer_data (object): legal_doc, legal_doc_type, phone_code, phone_number, email, full_name, bank, account_number, account_type

**Response:** Returns ticket and transaction details with PENDING status

### Merchant API
GET /api/v1/merchant/me
Retrieves merchant information including name, tax ID, email, currency, and current wallet balance.

POST /api/v1/transaction/{ticket}
Search transaction by TumiPay ticket or merchant reference. Returns full transaction details including status, amount, customer info, and response message.

## Webhooks

TumiPay sends POST requests to the ipn_url when transaction status changes.

**Webhook Payload Fields:**
- top_status: APPROVED, REJECTED, DECLINED, PENDING, CREATED, EXPIRED
- top_ticket: TumiPay transaction ID
- top_reference: Merchant reference
- top_amount: Transaction amount
- top_currency: Currency code
- top_payment_method: Payment method used
- top_bank_name: Bank involved
- top_response_message: Transaction outcome message
- top_user: Customer details object
- top_card: Card details (for card payments)

**Status Differences:**
- APPROVED: Successfully completed
- REJECTED: Failed during normal flow (bank declined, insufficient funds)
- DECLINED: Canceled by internal rules (fraud detection, limits, merchant config)
- PENDING: In progress, awaiting confirmation
- CREATED: Initiated but not processed
- EXPIRED: Timed out

**Security:**
- Header: x-trx-signature (SHA256 hash)
- Header: User-Agent: Tumipay/1.1
- Signature formula: SHA256({token, ticket, reference})

**Retry Schedule:**
1st retry: 5 minutes
2nd retry: 15 minutes after 1st
3rd retry: 30 minutes after 2nd
4th retry: 1 hour after 3rd
5th retry: 2 hours after 4th

Respond with 200 OK to confirm receipt. Implement idempotency using top_ticket or top_reference.

## Testing in Sandbox

### PayIn PSE Testing
1. Select any bank from the list
2. Complete the form with customer data
3. Use approved@tumipay.co or tumipay@tumipay.co in customer_data.email for approved transactions
4. Use any other email for rejected transactions

### PayIn Card Testing (Colombia Only)
Use these test cards with CVV 123:

**Approved (No 3DS):**
- 4456 5400 0000 0063
- 4456 5433 7171 3314
- 4456 5419 8206 8615

**Approved (With 3DS Challenge):**
- 4456 5280 8038 9860
- 4456 5292 6723 4200
- Enter any 6-digit code (e.g., 123456) for 3DS challenge

**Declined (With 3DS Challenge):**
- 4456 5300 0000 0031
- 4456 5300 0000 0106

### PayOut Testing
First create a successful PayIn to add funds to your sandbox balance, then initiate PayOut transactions.

## Common Response Messages

**Rejected PayOut Messages:**
- "Esta cuenta está inactiva/bloqueada" - Account inactive/blocked
- "La cuenta o Nit no corresponden" - Account or tax ID mismatch
- "El número de cuenta no existe" - Account number doesn't exist
- "El número de cuenta no es válido" - Invalid account number
- "Cuenta no autorizada" - Unauthorized account
- "El Nit no es válido" - Invalid tax ID
- "Excede el tope saldo de la cuenta destino" - Exceeds destination account balance limit

## Error Codes
- **01**: Operation successful
- **00**: Validation error or processing failed

## Additional Features

### Card Payments (Colombia Only)
- Supports 3D Secure authentication
- Customer submits card details on payment_url
- Charge processed asynchronously
- Final status delivered via webhook
- Webhook includes top_card object with card details (bin, last 4 digits, brand, type, issuing bank)

### Transaction Flow Patterns
1. Merchant creates transaction via API
2. TumiPay validates and returns ticket + payment_url (PayIn) or just ticket (PayOut)
3. Customer completes payment (PayIn only)
4. Payment provider processes transaction
5. TumiPay receives status update
6. TumiPay sends webhook to merchant ipn_url
7. Merchant responds with 200 OK

## Documentation Structure

### Guides
- Introduction: Overview of APIs and authorization
- Testing: Using sandbox and staging environments
- Webhooks: Real-time transaction notifications
- Merchant API Guide: Retrieve balance and search transactions

### Country Pages
- Colombia (/docs/co/introduction): CO-specific payment methods, banks, document types
- Peru (/docs/pe/introduction): PE-specific payment methods, banks, document types

### API Reference
- API Introduction: Authentication and environment details
- Authentication: Credential request and auth procedures
- PayIn API: Payment collection endpoints and examples
- PayOut API: Disbursement endpoints and examples
- Merchant API: Merchant info and transaction search
- Testing Reference: Sandbox testing guidelines
- Webhooks Reference: Webhook payload and security

## Best Practices

1. **Security:**
   - Use HTTPS for all requests
   - Store credentials in environment variables or secret managers
   - Validate webhook signatures using SHA256
   - Rotate credentials periodically
   - Never commit credentials to repositories

2. **Idempotency:**
   - Use unique reference IDs for each transaction
   - Store processed webhook events to prevent duplicate processing
   - Check top_ticket before processing webhooks

3. **Error Handling:**
   - Handle webhook retries properly
   - Log rejection messages for debugging
   - Implement proper timeout handling
   - Monitor transaction statuses

4. **Testing:**
   - Thoroughly test all payment methods in sandbox
   - Test webhook endpoint with retry scenarios
   - Verify signature validation logic
   - Test both approved and rejected flows

## Contact & Support
- Email: it@tumipay.co, tecnologia@tumipay.co, soporte@tumipay.co
- Request credentials and production access via email
- Contact support for limit adjustments, token rotation, or technical issues