Card Gateway API

Accept Visa, Mastercard, JCB, and Amex payments with 2D and 3D Secure support. Process card payments through a single API, with automatic fraud screening, velocity controls, and real-time settlement.

Overview

The Dapit Card Gateway provides a server-to-server API for processing credit and debit card payments. Send card details directly from your backend and receive real-time authorization results.

Authentication

All requests require your API key sent as a header:

X-Gateway-Key: your_api_key_here

You can also pass it as a query parameter api_key, but the header method is preferred. Your API key is available in the MaxaFi dashboard under the merchant's Instant Payments → Settings tab.

Base URL

# Production
https://www.maxafi.com/api/gateway/card_gateway.php

# All endpoints use the ?action= parameter
https://www.maxafi.com/api/gateway/card_gateway.php?action=create_charge

Create Charge

Process a card payment. The gateway automatically determines whether 3D Secure is required based on the card issuer and risk assessment.

// cURL
curl -X POST "https://www.maxafi.com/api/gateway/card_gateway.php?action=create_charge" \
  -H "Content-Type: application/json" \
  -H "X-Gateway-Key: your_api_key" \
  -d '{
    "amount": 49.99,
    "currency": "USD",
    "card_number": "4111111111111111",
    "card_expiry": "12/2027",
    "card_cvv": "123",
    "cardholder_name": "John Doe",
    "email": "john@example.com",
    "phone": "12125551234",
    "billing_address": "123 Main St",
    "billing_city": "New York",
    "billing_state": "NY",
    "billing_zip": "10001",
    "billing_country": "US",
    "order_id": "ORD-20260402-001",
    "description": "Widget purchase"
  }'

{
  "success": true,
  "charge_id": "ch_a1b2c3d4e5f6a7b8c9d0e1f2",
  "status": "succeeded",
  "amount": 49.99,
  "currency": "USD",
  "fees": {
    "mdr": 1.45,
    "transaction": 0.30,
    "total": 1.75
  },
  "net_amount": 48.24,
  "card_brand": "Visa",
  "card_last4": "1111",
  "merchant_order_id": "ORD-20260402-001"
}

{
  "success": true,
  "charge_id": "ch_a1b2c3d4e5f6a7b8c9d0e1f2",
  "status": "pending_3ds",
  "requires_action": true,
  "action_type": "3ds_redirect",
  "redirect_url": "https://3ds.provider.com/verify?token=abc123",
  "message": "Redirect the cardholder to redirect_url for 3D Secure verification.",
  "amount": 49.99,
  "currency": "USD"
}

{
  "success": true,
  "charge_id": "ch_a1b2c3d4e5f6a7b8c9d0e1f2",
  "status": "failed",
  "error_message": "Insufficient funds",
  "amount": 49.99,
  "currency": "USD"
}

3D Secure Flow

When the issuing bank requires 3D Secure verification, the create_charge response will include requires_action: true and a redirect_url.

Handling 3DS in Your Code

// After calling create_charge
if (response.requires_action && response.redirect_url) {
    // Store charge_id in your session/database
    saveChargeId(response.charge_id);

    // Redirect the cardholder to 3DS verification
    window.location.href = response.redirect_url;
}

// Your webhook endpoint receives the result:
{
  "event": "charge.succeeded",
  "charge_id": "ch_a1b2c3d4e5f6a7b8c9d0e1f2",
  "status": "succeeded",
  "amount": 49.99,
  "confirmed_at": "2026-04-02T14:30:00Z"
}

Get Charge

Retrieve the current status and details of a charge.

{
  "success": true,
  "charge_id": "ch_a1b2c3d4e5f6a7b8c9d0e1f2",
  "status": "succeeded",
  "amount": 49.99,
  "currency": "USD",
  "fees": { "mdr": 1.45, "transaction": 0.30, "total": 1.75 },
  "net_amount": 48.24,
  "card_brand": "Visa",
  "card_last4": "1111",
  "merchant_order_id": "ORD-20260402-001",
  "description": "Widget purchase",
  "created_at": "2026-04-02 14:25:00",
  "confirmed_at": "2026-04-02 14:25:02",
  "refunded_amount": 0
}

Create Refund

Refund a succeeded charge. Supports full and partial refunds.

{
  "success": true,
  "refund_id": "rf_x1y2z3a4b5c6d7e8f9g0h1i2",
  "charge_id": "ch_a1b2c3d4e5f6a7b8c9d0e1f2",
  "status": "succeeded",
  "amount": 49.99,
  "refund_fee": 0.00,
  "net_refund": 49.99
}

List Charges

Retrieve a paginated list of your charges with optional filters.

Charge Statuses

Webhooks

Set your callback_url in the MaxaFi dashboard (Instant Payments → Settings). We POST JSON to this URL when:

• A 3DS charge completes (succeeded or failed)
• A processing charge reaches final status
• A refund is processed

Webhook Payload

{
  "event": "charge.succeeded",
  "charge_id": "ch_a1b2c3d4e5f6a7b8c9d0e1f2",
  "merchant_order_id": "ORD-20260402-001",
  "amount": 49.99,
  "currency": "USD",
  "status": "succeeded",
  "card_brand": "Visa",
  "card_last4": "1111",
  "confirmed_at": "2026-04-02T14:30:00Z",
  "timestamp": "2026-04-02T14:30:01+00:00"
}

Webhook Events

Error Codes

When a request fails, the response includes success: false and an error field:

{
  "success": false,
  "error": "Amount exceeds single transaction limit of USD 5,000.00"
}

Test Cards

Use these card numbers in test mode. The first card below is the gateway provider's official test card with specific CVV and expiry.

Code Examples

PHP

// PHP — Create a charge
$ch = curl_init('https://www.maxafi.com/api/gateway/card_gateway.php?action=create_charge');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-Gateway-Key: your_api_key'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => 49.99,
        'currency' => 'USD',
        'card_number' => '4111111111111111',
        'card_expiry' => '12/2027',
        'card_cvv' => '123',
        'cardholder_name' => 'John Doe',
        'email' => 'john@example.com',
        'phone' => '12125551234',
        'billing_address' => '123 Main St',
        'billing_city' => 'New York',
        'billing_state' => 'NY',
        'billing_zip' => '10001',
        'billing_country' => 'US',
        'order_id' => 'ORD-001',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($result['success'] && $result['status'] === 'succeeded') {
    // Payment approved!
    echo "Charge " . $result['charge_id'] . " approved.";
} elseif ($result['requires_action']) {
    // Redirect for 3DS
    header('Location: ' . $result['redirect_url']);
} else {
    // Declined
    echo "Error: " . $result['error_message'];
}

Node.js

// Node.js — Create a charge
const response = await fetch(
  'https://www.maxafi.com/api/gateway/card_gateway.php?action=create_charge',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Gateway-Key': 'your_api_key',
    },
    body: JSON.stringify({
      amount: 49.99,
      currency: 'USD',
      card_number: '4111111111111111',
      card_expiry: '12/2027',
      card_cvv: '123',
      cardholder_name: 'John Doe',
      email: 'john@example.com',
      phone: '12125551234',
      billing_address: '123 Main St',
      billing_city: 'New York',
      billing_state: 'NY',
      billing_zip: '10001',
      billing_country: 'US',
      order_id: 'ORD-001',
    }),
  }
);
const data = await response.json();

if (data.status === 'succeeded') {
  console.log('Approved:', data.charge_id);
} else if (data.requires_action) {
  console.log('Redirect to:', data.redirect_url);
} else {
  console.log('Declined:', data.error_message);
}

Python

# Python — Create a charge
import requests

result = requests.post(
    'https://www.maxafi.com/api/gateway/card_gateway.php?action=create_charge',
    headers={
        'Content-Type': 'application/json',
        'X-Gateway-Key': 'your_api_key',
    },
    json={
        'amount': 49.99,
        'currency': 'USD',
        'card_number': '4111111111111111',
        'card_expiry': '12/2027',
        'card_cvv': '123',
        'cardholder_name': 'John Doe',
        'email': 'john@example.com',
        'phone': '12125551234',
        'billing_address': '123 Main St',
        'billing_city': 'New York',
        'billing_state': 'NY',
        'billing_zip': '10001',
        'billing_country': 'US',
    }
).json()

if result['status'] == 'succeeded':
    print(f"Approved: {result['charge_id']}")
elif result.get('requires_action'):
    print(f"3DS redirect: {result['redirect_url']}")
else:
    print(f"Declined: {result.get('error_message')}")