Get optimized payment quotes across all regions. Returns fee breakdowns, success rates, and the recommended route for your payment intent.

Request Body

{
  "intent": {
    "amount": 99.99,
    "currency": "EUR",
    "paymentMethod": "card",
    "userCountry": "DE",         // optional
    "cardToken": "tok_visa_4242", // optional
    "customerEmail": "user@example.com"
  },
  "regions": ["EU", "US"],      // optional filter
  "includeUnavailable": false  // optional
}

Payment Intent Fields

Response

{
  "success": true,
  "data": {
    "quotes": [
      {
        "region": "EU",
        "routerId": "router_eu_a1b2c3",
        "routerName": "European Union Gateway",
        "totalCost": 1.65,
        "feeBreakdown": {
          "percentFee": 1.4,
          "fixedFee": 0.25,
          "fxFee": 0,
          "crossBorderFee": 0
        },
        "successRate": 0.987,
        "latencyMs": 185,
        "score": 98.2,
        "available": true,
        "validForSec": 300
      }
    ],
    "recommended": { ... },
    "totalRegions": 5
  }
}

Execute a payment through the specified region. Supports idempotency keys for safe retries.

Required Headers

Request Body

{
  "intent": {
    "amount": 99.99,
    "currency": "EUR",
    "paymentMethod": "card",
    "cardToken": "tok_visa_4242",
    "customerEmail": "customer@example.com",
    "description": "Order #12345",
    "returnUrl": "https://yoursite.com/success",
    "webhookUrl": "https://yoursite.com/webhooks/geopay"
  },
  "region": "EU",
  "routerId": "router_eu_a1b2c3",
  "idempotencyKey": "order_12345_attempt_1"
}

Response

{
  "success": true,
  "data": {
    "intentId": "pi_abc123def456",
    "status": "succeeded",
    "regionUsed": "EU",
    "routerId": "router_eu_a1b2c3",
    "providerPaymentId": "ch_xyz789",
    "costApplied": 1.65,
    "amountCharged": 99.99,
    "currencyCharged": "EUR",
    "processedAt": "2024-01-15T12:00:00.000Z",
    "receiptUrl": "https://geopay403.xyz/receipts/pi_abc123",
    "authCode": "A1B2C3"
  }
}

Payment Status Values

Process a full or partial refund for a completed payment. Supports idempotency for safe retries.

Request Body

{
  "refundIntent": {
    "paymentIntentId": "pi_abc123def456",
    "providerPaymentId": "ch_xyz789",
    "amount": 50.00,  // optional, full refund if omitted
    "reason": "requested_by_customer",
    "metadata": {
      "refund_ticket": "TICKET-789"
    }
  },
  "region": "EU",
  "idempotencyKey": "refund_pi_abc123_1"
}

Refund Reason Codes

Response

{
  "success": true,
  "data": {
    "paymentIntentId": "pi_abc123def456",
    "refundId": "re_xyz789",
    "status": "succeeded",
    "amount": 50.00,
    "currency": "EUR",
    "regionUsed": "EU",
    "processedAt": "2024-01-15T14:00:00.000Z"
  }
}

Webhook Events

GeoPay sends webhook events to notify your application about payment status changes. All webhooks are signed with HMAC-SHA256 for security.

Webhook Payload Structure

{
  "id": "evt_abc123",
  "type": "payment.succeeded",
  "created": "2024-01-15T12:00:00.000Z",
  "data": {
    "intentId": "pi_abc123def456",
    "providerPaymentId": "ch_xyz789",
    "amount": 99.99,
    "currency": "EUR",
    "region": "EU",
    "routerId": "router_eu_a1b2c3",
    "metadata": {}
  }
}

Event Types

Verifying Webhooks

const crypto = require('crypto');

function verifyWebhook(payload, signature, timestamp, secret) {
  const signedPayload = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Error Codes

All errors follow a consistent format with machine-readable codes and human-readable messages.

Error Response Format

{
  "success": false,
  "error": {
    "code": "PAYMENT_DECLINED",
    "message": "The payment was declined by the processor",
    "details": {
      "decline_code": "insufficient_funds"
    }
  },
  "requestId": "req_abc123",
  "timestamp": "2024-01-15T12:00:00.000Z"
}

Payment Error Codes

Region Error Codes

System Error Codes