Card Payments - 88Pay Documentation

Overview

Card payments are the most popular payment method, offering instant processing and familiar checkout experience for customers.

Supported Cards

Visa, Mastercard, Amex

Processing Time

Instant confirmation

3D Secure

Fraud protection included

How It Works

Create Card Payment

Request

curl -X POST "https://api-sandbox.88pay.io/api/transactions/charges" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-session-id: YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "PAYIN",
    "method_code": "CARDS",
    "method_category": "CARD",
    "amount": 50000,
    "currency": "COP",
    "country": "COL",
    "description": "Order #12345",
    "customer_id": "user_001",
    "notification_url": "https://yoursite.com/webhook",
    "return_url": "https://yoursite.com/success"
  }'

Response

{
  "status": "Success",
  "code": 200,
  "data": {
    "urlCheckout": "https://link.88pay.io/ABC123",
    "reference": "IP9BD7CJES6",
    "amount": 50000,
    "currency": "COP"
  }
}

Customer Experience

Redirect to Checkout

Customer is redirected to urlCheckout - a secure 88Pay hosted page

Enter Card Details

Customer enters:

Card number
Expiry date
CVV
Cardholder name

3D Secure (if required)

Customer completes additional verification:

SMS OTP
Bank app approval
Biometric authentication

Payment Processed

Card network processes payment (~2-5 seconds)

Return to Site

Customer redirected to your return_url

Important: Don’t rely on return_url for order fulfillment. Always use webhooks - customers may close browser before redirect.

3D Secure Authentication

88Pay automatically triggers 3D Secure (3DS) when required by:

Card issuer requirements
Transaction amount thresholds
Risk assessment

3DS Flow

Frictionless
Challenge

Low-risk transactions

No customer action required
Approved in background
Seamless experience

Used for: Returning customers, low amounts, low-risk profiles

3D Secure protects you from fraud chargebacks. Liability shifts to card issuer for 3DS-authenticated transactions.

Currency & Country Support

Country	Currency	Cards Accepted
🇨🇴 Colombia	COP	Visa, Mastercard, Amex
🇲🇽 Mexico	MXN	Visa, Mastercard, Amex
🇧🇷 Brazil	BRL	Visa, Mastercard, Amex
🇨🇱 Chile	CLP	Visa, Mastercard, Amex
🇵🇪 Peru	PEN	Visa, Mastercard, Amex
🇦🇷 Argentina	ARS	Visa, Mastercard

See all countries →

Transaction Limits

Colombia (COP)
Mexico (MXN)
Brazil (BRL)
Other Countries

Min: 1,000 COP (~$0.25 USD)Max: 20,000,000 COP (~$5,000 USD)Daily limit: 50,000,000 COP per customer

Webhook Notifications

You’ll receive webhooks for these statuses:

COMPLETED
REJECTED

    {
      "transaction_status": "COMPLETED",
      "transaction_reference": "IP9BD7CJES6",
      "transaction_amount": "50000",
      "transaction_payment_method": "CREDIT_CARD"
    }

Action: Fulfill order, send confirmation email

    {
      "transaction_status": "REJECTED",
      "transaction_reference": "IP9BD7CJES6",
      "transaction_amount": "50000",
      "transaction_payment_method": "CREDIT_CARD"
    }

Reasons:

Card declined by issuer
Insufficient funds
3DS authentication failed
Fraud detected

Action: Notify customer, offer retry

Webhook implementation guide →

Testing

Sandbox Test Cards

Use these cards in sandbox environment:

Card Number	Brand	Result	3DS
`4111111111111111`	Visa	✅ Approved	No
`5555555555554444`	Mastercard	✅ Approved	No
`378282246310005`	Amex	✅ Approved	No
`4000000000000002`	Visa	❌ Declined	No
`4000000000000069`	Visa	⏳ Pending	No
`4000000000003220`	Visa	✅ Approved	Yes (challenge)

For all test cards:

CVV: Any 3 digits (4 for Amex)
Expiry: Any future date (e.g., 12/25)
Name: Any name

Test cards only work in sandbox. Use real cards in production.

Common Issues

Customer not redirected to checkout

Problem: urlCheckout not received or redirect failsSolutions:

    // Check response contains urlCheckout
    if (!data.urlCheckout) {
      console.error('No checkout URL in response');
      return;
    }
    
    // Ensure proper redirect
    window.location.href = data.urlCheckout; // ✅ Works
    window.location = data.urlCheckout;      // ✅ Works
    location.href = data.urlCheckout;        // ✅ Works
    
    // Avoid these:
    window.open(data.urlCheckout);           // ❌ Opens new tab
    <a href={data.urlCheckout}>Pay</a>       // ❌ Requires click

Payment approved but order not fulfilled

Problem: Relying on return_url instead of webhooksSolution:

    // ❌ BAD: Only checking return URL
    app.get('/success', (req, res) => {
      fulfillOrder(req.query.reference); // UNSAFE!
    });
    
    // ✅ GOOD: Using webhooks
    app.post('/webhook', (req, res) => {
      if (req.body.transaction_status === 'COMPLETED') {
        fulfillOrder(req.body.transaction_reference);
      }
      res.status(200).json({ received: true });
    });

Card declined with no clear reason

Common reasons:

Insufficient funds
Card expired
Incorrect CVV
3DS authentication failed
Card blocked by issuer
International transactions disabled

Customer actions:

Verify card details
Check with bank
Try different card
Enable international transactions

3DS authentication taking too long

This is normal:

3DS adds 10-60 seconds to checkout
Bank may require app approval
Customer may need to find phone

Best practice:

Set webhook timeout to 10 minutes
Show “Processing…” message
Don’t assume immediate response

Best Practices

Always Use Webhooks

Never rely solely on return_url for order fulfillment

Set Timeouts

Allow 10 minutes for 3DS authentication

Handle Declines

Offer to retry with different card

Show Progress

Display “Processing…” during payment

Store Reference

Save reference for tracking and support

Test Thoroughly

Test all scenarios: approved, declined, pending, 3DS

Security Notes

PCI Compliance: Never collect card details directly. Always redirect to 88Pay checkout page.

What 88Pay handles:

✅ Card data collection
✅ PCI DSS compliance
✅ 3D Secure authentication
✅ Fraud detection
✅ Card tokenization

What you handle:

✅ Webhook verification
✅ Order fulfillment
✅ Customer communication

Next Steps

Webhooks

Implement payment notifications

Testing

Test card payments

Error Handling

Handle declined payments

API Reference

Full technical documentation

Available Methods

​Overview

Supported Cards

Processing Time

3D Secure

​How It Works

​Create Card Payment

​Request

​Response

​Customer Experience

​3D Secure Authentication

​3DS Flow

​Currency & Country Support

​Transaction Limits

​Webhook Notifications

​Testing

​Sandbox Test Cards

​Common Issues

​Best Practices

Always Use Webhooks

Set Timeouts

Handle Declines

Show Progress

Store Reference

Test Thoroughly

​Security Notes

​Next Steps

Webhooks

Testing

Error Handling

API Reference

Overview

How It Works

Create Card Payment

Request

Response

Customer Experience

3D Secure Authentication

3DS Flow

Currency & Country Support

Transaction Limits

Webhook Notifications

Testing

Sandbox Test Cards

Common Issues

Best Practices

Security Notes

Next Steps