🧪 Testing in Sandbox
Testing in Sandbox
The Koywe sandbox environment allows you to test all payment flows with simulated transactions before going live.
Sandbox Environment
Base URL
All sandbox API requests use:
Getting Test Credentials
Contact soporte@koywe.com to receive:
- Sandbox API Key
- Sandbox Secret
- Organization ID
- Merchant ID
Sandbox vs Production: Sandbox credentials are completely separate from production. No real money is involved in sandbox testing.
Test Payment Methods by Country
Colombia (COP) 🇨🇴
PSE (Pagos Seguros en Línea)
Test Banks:
BANCOLOMBIADAVIVIENDABOGOTAOCCIDENTE
Usage:
Behavior:
- Payment link is fully functional in sandbox
- Follow the simulated payment process
- You can choose to succeed or fail the payment during the flow
- Allows testing of complete user experience
Nequi
Usage:
Behavior:
- Generates a test QR code
- After scanning the QR code, you’ll be given options to succeed or fail the payment
- Simulates the complete Nequi payment experience
Brazil (BRL) 🇧🇷
PIX Static
Usage:
Behavior:
- Generates a test QR code
- After scanning the QR code, you’ll be given options to succeed or fail the payment
- Simulates the complete PIX payment experience
PIX Dynamic
Usage:
Behavior:
- Generates a test QR code
- After scanning the QR code, you’ll be given options to succeed or fail the payment
- Similar to PIX_STATIC with interactive testing options
Mexico (MXN) 🇲🇽
SPEI (Instant Settlement ⚡)
Usage:
Behavior:
- Provides test bank account details
- Auto-completes after order creation
- Simulates bank transfer confirmation
Cards
Test Card Numbers:
- Success:
4242424242424242 - Decline:
4000000000000002 - Insufficient Funds:
4000000000009995
Usage:
Chile (CLP) 🇨🇱
Khipu
Usage:
Behavior:
- Payment link is fully functional in sandbox
- Follow the simulated payment process
- You can choose to succeed or fail the payment during the flow
- Allows testing of complete user experience
Argentina (ARS) 🇦🇷
Multiple Local Methods
Usage:
Behavior:
- Payment link is fully functional in sandbox
- You can choose to succeed or fail the payment during the flow
Test Scenarios
Interactive Testing: Most payment methods (PSE, Khipu) provide functional payment links where you can follow the simulated payment process and choose to succeed or fail. QR-based methods (PIX, Nequi) give you options after scanning the code.
Successful Payment Flow
Test a successful end-to-end payment:
Expected flow:
Failed Payment Scenario
Test payment failure handling:
Use the special test amount 666 to simulate a failed payment:
Expected flow:
Expired Payment
Test order expiration:
Payment Link Flow (PAYMENT_LINK)
Test the complete Koywe-branded checkout experience:
PAYMENT_LINK is perfect for e-commerce! No contact or payment method needed - just create a link and share it. The customer enters their own data and selects their payment method in the Koywe checkout.
Testing the checkout flow:
- Create the payment link using the code above
- Copy the
paymentUrl - Open it in your browser
- You’ll see the Koywe-branded checkout page
- Fill in test customer information
- Select a payment method
- Complete the simulated payment (choose success or fail)
- Verify webhook notification is received
Use Case: PAYMENT_LINK is ideal for:
- E-commerce checkout pages
- Invoice payment requests
- Email/WhatsApp payment links
- QR code payments
- Quick payment collections without storing customer data
Testing Webhooks
Setup Webhook Endpoint
Use webhook testing tools:
- webhook.site - Instant webhook URL
- ngrok - Tunnel to localhost
- RequestBin - Webhook inspector
Using webhook.site
Expected Webhook Events
For a successful PAYIN:
order.created- Order is createdorder.pending- Waiting for paymentorder.processing- Payment being processedorder.paid- Payment confirmedorder.completed- Funds credited
Webhook Payload Example
Test Data
Test Contacts
Use these test document numbers (all valid in sandbox):
Colombia
Brazil
Mexico
Chile
Test Bank Accounts
For PAYOUT testing:
Colombia
Brazil
Mexico
Chile
Testing Crypto Operations
Automatic Test Network Selection
Production Network Names in Sandbox: When using production network names like ETHEREUM, POLYGON, or BSC in sandbox, the system automatically routes to test networks (Sepolia, Amoy, BSC Testnet respectively). You don’t need to specify testnet names explicitly.
Test Networks
Sandbox automatically uses these testnets:
Example: Specify "network": "POLYGON" in your request, and sandbox will use Amoy automatically.
Test Wallet Address
Use this address for receiving test crypto:
Never use production addresses in sandbox - Always use test/burn addresses like the zero address above.
ONRAMP Test
OFFRAMP Test
Rate Limits
Sandbox environment has the following limits:
Rate limit headers are included in all responses:
X-RateLimit-Limit: Total requests allowedX-RateLimit-Remaining: Requests remainingX-RateLimit-Reset: Unix timestamp when limit resets
Testing Best Practices
Test All Order Types
Test each order type:
- ✅ PAYIN with different payment methods
- ✅ PAYOUT to different countries
- ✅ BALANCE_TRANSFER between currencies
- ✅ ONRAMP for crypto purchases
- ✅ OFFRAMP for crypto sales
- ✅ PAYMENT_LINK with expiry
Test Error Scenarios
Test error handling:
- ✅ Invalid API credentials
- ✅ Insufficient balance for PAYOUT
- ✅ Invalid bank account details
- ✅ Expired quotes
- ✅ Failed payments (amount: 666)
- ✅ Webhook signature verification
Test Idempotency
Common Test Workflows
E-Commerce Checkout Flow
Provider Payout Flow
Moving to Production
When you’re ready to go live:
Production Checklist
- Production API credentials obtained
- Base URL updated to production
- Webhook URLs pointing to production servers
- Webhook signature verification implemented
- Error handling tested
- Logging and monitoring setup
- Small test transaction successful
- Team trained on production processes
Troubleshooting
Order Stuck in PENDING
Issue: Order created but stays in PENDING status
Solution:
- In sandbox, wait 30-60 seconds for auto-completion
- Check if you used the failure test amount (666)
- Verify payment method is correct for country
Webhooks Not Received
Issue: No webhook events arriving
Solution:
- Verify webhook URL is publicly accessible
- Check firewall/security settings
- Use webhook.site to test
- Verify webhook endpoint is configured
Insufficient Balance Error
Issue: PAYOUT fails with insufficient balance
Solution:
- Check virtual account balance
- Create PAYIN orders to add funds to sandbox account
- Verify you’re checking the correct currency balance
Need Help?
soporte@koywe.com
For sandbox access issues or testing questions
Common issues and solutions
Complete API documentation
5-minute integration guide