cURL

curl --request GET \
  --url https://apay.caibo.digital/payment-requests/handle/{id}/{paymentMethod}

const options = {method: 'GET'};

fetch('https://apay.caibo.digital/payment-requests/handle/{id}/{paymentMethod}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://apay.caibo.digital/payment-requests/handle/{id}/{paymentMethod}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://apay.caibo.digital/payment-requests/handle/{id}/{paymentMethod}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://apay.caibo.digital/payment-requests/handle/{id}/{paymentMethod}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>"
}

GET

payment-requests

handle

{id}

{paymentMethod}

cURL

curl --request GET \
  --url https://apay.caibo.digital/payment-requests/handle/{id}/{paymentMethod}

const options = {method: 'GET'};

fetch('https://apay.caibo.digital/payment-requests/handle/{id}/{paymentMethod}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://apay.caibo.digital/payment-requests/handle/{id}/{paymentMethod}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://apay.caibo.digital/payment-requests/handle/{id}/{paymentMethod}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://apay.caibo.digital/payment-requests/handle/{id}/{paymentMethod}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>"
}

{
  "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

Parameter	Description	Type	Required
`id`	Payment request identifier	integer (int64)	YES
`paymentMethod`	Payment method to use for processing	PaymentMethod enum	YES

Payment Methods

The following payment methods are supported:

Method	Description	Use Case
`CREDIT_CARD`	Credit/debit card payments	Standard card processing
`APPLE_PAY`	Apple Pay digital wallet	iOS/Safari payments
`GOOGLE_PAY`	Google Pay digital wallet	Android/Chrome payments
`UPI`	Unified Payments Interface	Indian market payments
`BANK_TRANSFER`	Direct bank transfers	ACH/wire transfers
`CRYPTOCURRENCY`	Digital currency payments	Bitcoin, Ethereum, etc.
`PAYPAL`	PayPal wallet payments	PayPal 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

Code	Description
`200`	OK - Payment handling initiated successfully
`400`	Bad Request - Invalid payment method or request
`404`	Not Found - Payment request not found
`422`	Unprocessable Content - Payment method not supported for this request
`500`	Internal 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

Start with Basic: Begin with credit card as fallback
Detect Capabilities: Check for wallet/UPI support
Offer Options: Present available payment methods
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

Get Payment Request: Retrieve payment request details
Payment Status Check: Check payment status
Release Payment Request: Release payment request
Create Payment Request: Create new payment requests

Path Parameters

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

Customers

Payment Requests

Handle Payment Request

Overview

API Endpoint

Authentication

Path Parameters

Payment Methods

Response

Processing Information

Payment Details

Example Request

Example Response

Response Status Codes

Error Response Examples

Invalid Payment Method

Payment Request Not Found

Unprocessable Payment Method

Payment Method Specific Handling

Credit Card Processing

Digital Wallet Processing

UPI Processing

Implementation Examples

JavaScript/Node.js

Payment Method Selection

Integration Patterns

Progressive Enhancement

Mobile Optimization

Best Practices

Payment Method Selection

Error Handling

Security

Path Parameters

Response

​Overview

​API Endpoint

​Authentication

​Path Parameters

​Payment Methods

​Response

​Processing Information

​Payment Details

​Example Request

​Example Response

​Response Status Codes

​Error Response Examples

​Invalid Payment Method

​Payment Request Not Found

​Unprocessable Payment Method

​Payment Method Specific Handling

​Credit Card Processing

​Digital Wallet Processing

​UPI Processing

​Implementation Examples

​JavaScript/Node.js

​Payment Method Selection

​Integration Patterns

​Progressive Enhancement

​Mobile Optimization

​Best Practices

​Payment Method Selection

​Error Handling

​Security

​Related Endpoints

Path Parameters

Response

Overview

API Endpoint

Authentication

Path Parameters

Payment Methods

Response

Processing Information

Payment Details

Example Request

Example Response

Response Status Codes

Error Response Examples

Invalid Payment Method

Payment Request Not Found

Unprocessable Payment Method

Payment Method Specific Handling

Credit Card Processing

Digital Wallet Processing

UPI Processing

Implementation Examples

JavaScript/Node.js

Payment Method Selection

Integration Patterns

Progressive Enhancement

Mobile Optimization

Best Practices

Payment Method Selection

Error Handling

Security

Related Endpoints