Skip to main content
GET
/
payment-requests
/
handle
/
{id}
/
{paymentMethod}
cURL
curl --request GET \
  --url https://apay.caibo.digital/payment-requests/handle/{id}/{paymentMethod}
{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>"
}

​
Overview

Process a payment request using a specific payment method. This endpoint allows you to handle payment requests with different payment methods like credit cards, digital wallets, or alternative payment options.

​
API Endpoint

GET /payment-requests/handle/{id}/{paymentMethod}

​
Authentication

  • HTTP Header: X-API-Key with your API key obtained from the dashboard
  • Content Type: application/json

​
Path Parameters

ParameterDescriptionTypeRequired
idPayment request identifierinteger (int64)YES
paymentMethodPayment method to use for processingPaymentMethod enumYES

​
Payment Methods

The following payment methods are supported:
MethodDescriptionUse Case
CREDIT_CARDCredit/debit card paymentsStandard card processing
APPLE_PAYApple Pay digital walletiOS/Safari payments
GOOGLE_PAYGoogle Pay digital walletAndroid/Chrome payments
UPIUnified Payments InterfaceIndian market payments
BANK_TRANSFERDirect bank transfersACH/wire transfers
CRYPTOCURRENCYDigital currency paymentsBitcoin, Ethereum, etc.
PAYPALPayPal wallet paymentsPayPal account holders

​
Response

Returns payment handling result including:

​
Processing Information

  • Status: Payment processing status
  • Transaction ID: Generated transaction identifier
  • Redirect URL: URL for customer to complete payment (if required)
  • Processing Time: Estimated processing duration

​
Payment Details

  • Method Used: Confirmed payment method
  • Amount: Transaction amount and currency
  • Fees: Processing fees (if applicable)
  • Exchange Rate: Currency conversion rate (if applicable)

​
Example Request

curl -X GET \
  "https://apay.caibo.digital/payment-requests/handle/12345/CREDIT_CARD" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json"

​
Example Response

{
  "status": "processing",
  "transactionId": "txn_abc123def456",
  "paymentMethod": "CREDIT_CARD",
  "redirectUrl": "https://secure.caibo.io/payment/complete/txn_abc123def456",
  "estimatedProcessingTime": "2-5 minutes",
  "amount": {
    "value": 100.50,
    "currency": "USD"
  },
  "fees": {
    "processingFee": 2.50,
    "currency": "USD"
  },
  "expiresAt": "2024-01-15T11:30:00Z",
  "nextSteps": {
    "action": "redirect_customer",
    "description": "Redirect customer to complete 3D Secure authentication",
    "timeout": 900
  }
}

​
Response Status Codes

CodeDescription
200OK - Payment handling initiated successfully
400Bad Request - Invalid payment method or request
404Not Found - Payment request not found
422Unprocessable Content - Payment method not supported for this request
500Internal Server Error - Processing error occurred

​
Error Response Examples

​
Invalid Payment Method

{
  "error": {
    "code": "INVALID_PAYMENT_METHOD",
    "message": "Payment method 'INVALID_METHOD' is not supported",
    "supportedMethods": ["CREDIT_CARD", "APPLE_PAY", "GOOGLE_PAY", "UPI"]
  }
}

​
Payment Request Not Found

{
  "error": {
    "code": "PAYMENT_REQUEST_NOT_FOUND",
    "message": "Payment request with ID 12345 not found or expired"
  }
}

​
Unprocessable Payment Method

{
  "error": {
    "code": "PAYMENT_METHOD_NOT_AVAILABLE",
    "message": "APPLE_PAY is not available for this payment request",
    "reason": "Customer device does not support Apple Pay"
  }
}

​
Payment Method Specific Handling

​
Credit Card Processing

GET /payment-requests/handle/12345/CREDIT_CARD
  • Initiates 3D Secure authentication if required
  • Returns redirect URL for card verification
  • Processes payment immediately for non-3DS cards

​
Digital Wallet Processing

GET /payment-requests/handle/12345/APPLE_PAY
  • Validates wallet availability on customer device
  • Initiates biometric authentication flow
  • Returns wallet-specific payment session

​
UPI Processing

GET /payment-requests/handle/12345/UPI
  • Validates UPI ID format and availability
  • Generates UPI payment link
  • Supports QR code generation for mobile apps

​
Implementation Examples

​
JavaScript/Node.js

async function handlePaymentRequest(paymentId, paymentMethod, apiKey) {
  try {
    const response = await fetch(
      `https://apay.caibo.digital/payment-requests/handle/${paymentId}/${paymentMethod}`,
      {
        method: 'GET',
        headers: {
          'X-API-Key': apiKey,
          'Content-Type': 'application/json'
        }
      }
    );
    
    if (!response.ok) {
      const error = await response.json();
      throw new Error(`Payment handling failed: ${error.message}`);
    }
    
    const result = await response.json();
    
    // Handle different response types
    if (result.redirectUrl) {
      // Redirect customer to complete payment
      window.location.href = result.redirectUrl;
    } else if (result.status === 'completed') {
      // Payment completed immediately
      console.log('Payment completed:', result.transactionId);
    }
    
    return result;
    
  } catch (error) {
    console.error('Error handling payment:', error);
    throw error;
  }
}

// Usage examples
await handlePaymentRequest(12345, 'CREDIT_CARD', 'your-api-key');
await handlePaymentRequest(12345, 'APPLE_PAY', 'your-api-key');
await handlePaymentRequest(12345, 'UPI', 'your-api-key');

​
Payment Method Selection

function selectPaymentMethod(availableMethods, customerPreference) {
  const methodPriority = {
    'APPLE_PAY': 1,
    'GOOGLE_PAY': 2,
    'CREDIT_CARD': 3,
    'UPI': 4,
    'BANK_TRANSFER': 5
  };
  
  // Filter available methods by customer device/preference
  const supportedMethods = availableMethods.filter(method => {
    switch (method) {
      case 'APPLE_PAY':
        return window.ApplePaySession && ApplePaySession.canMakePayments();
      case 'GOOGLE_PAY':
        return window.google && window.google.payments;
      case 'UPI':
        return customerPreference.country === 'IN';
      default:
        return true;
    }
  });
  
  // Sort by priority and return best option
  return supportedMethods.sort((a, b) => 
    methodPriority[a] - methodPriority[b]
  )[0];
}

​
Integration Patterns

​
Progressive Enhancement

  1. Start with Basic: Begin with credit card as fallback
  2. Detect Capabilities: Check for wallet/UPI support
  3. Offer Options: Present available payment methods
  4. Handle Gracefully: Fall back if preferred method fails

​
Mobile Optimization

  • Wallet Priority: Prioritize digital wallets on mobile
  • UPI for India: Offer UPI as primary option in Indian market
  • Touch/Face ID: Leverage biometric authentication
  • App Deep Links: Support payment app integration

​
Best Practices

​
Payment Method Selection

  • Device Detection: Choose methods based on customer device
  • Geographic Optimization: Offer region-appropriate methods
  • Fallback Strategy: Always provide alternative payment options
  • User Preference: Remember customer’s preferred methods

​
Error Handling

  • Graceful Degradation: Fall back to alternative methods
  • Clear Messaging: Provide helpful error messages
  • Retry Logic: Implement appropriate retry mechanisms
  • Support Integration: Link to customer support for complex issues

​
Security

  • Method Validation: Verify payment method availability before processing
  • Timeout Handling: Implement appropriate timeouts for each method
  • Fraud Detection: Monitor for suspicious payment method patterns
  • Compliance: Ensure compliance with payment method regulations

Path Parameters

​
id
integer<int64>
required
​
paymentMethod
enum<integer>
required
Available options:
0,
1,
2,
3,
4,
5,
6,
7,
8,
9,
10,
11,
13,
14,
15,
16,
17,
18,
19,
20

Response

OK