Payment API Documentation

{
  "first_name": "John",
  "last_name": "Doe",
  "line1": "123 Main Street",
  "country": "US",
  "state": "NY",
  "city": "New York",
  "postal_code": "10001",
  "ip_address": "192.168.1.100",
  "email": "john.doe@example.com",
  "phone": "+19876543210",
  "amount": "100.50",
  "currency": "USD",
  "card_number": "4242424242424242",
  "card_expiry_month": "01",
  "card_expiry_year": "2028",
  "card_cvv": "123",
  "return_url": "https://yoursite.com/payment/return",
  "webhook_url": "https://yoursite.com/webhooks/payment",
  "merchant_transaction_id": "ORDER-12345"
}

{
  "status": "success",
  "reason": "Payment completed",
  "merchant_transaction_id": "MRF-3",
  "transaction_id": "txn_bY32XICH0yXnp0s7"
}

{
  "status": "processing",
  "3ds_url": "http://localhost:8002/test-gateway/authentication/eyJpdiI6Ikxmd0ZRTTBQR0pvcGFTSXdsdnRKdXc9PSIsInZhbHVlIjoiQnVVQ1I3S1BKQVlvNGU4YTRmdjhMMFpTRVF5eGwrTEVhMEhRZjE1MHliaz0iLCJtYWMiOiJiZTBiMmQwNTE2NzJjN2MyNTVmNzEwZTNjMTE0MWYzOTBmMTdmNjBhNjFkZTMyNzE0MWVjYTNjY2RhZWExM2EyIiwidGFnIjoiIn0=",
  "reason": "Payment authentication reqiured.",
  "merchant_transaction_id": "MRF-1",
  "transaction_id": "txn_SAx5Fyj4X1pyFIYO"
}

{
  "status": "declined",
  "reason": "Payment failed.",
  "merchant_transaction_id": "MRF-2",
  "transaction_id": "txn_KhZl1qEc33JamngW"
}

{
  "status": "declined",
  "reason": "The first name field is required.",
  "merchant_transaction_id": "MRF-141"
}

{
  "merchant_transaction_id": "ORDER-12345"
}

{
  "success": true,
  "data": {
    "transaction_id": "txn_Cf7Gr7PgqIObMAcM",
    "merchant_transaction_id": "MRF-123",
    "status": "success",
    "amount": 10,
    "currency": "USD",
    "message": "Payment completed.",
    "customer_info": {
      "phone": "+19876549872",
      "line1": "Address",
      "postal_code": "12345",
      "city": "MINS",
      "state": "TX",
      "name": "Fname Lname",
      "email": "test@gmail.com",
      "country": "US"
    },
    "created_at": "2025-10-06 18:19:53",
    "processed_at": "2025-10-06 18:19:53",
    "payment_info": {
      "card_number": "4242",
      "card_expiry_month": 1,
      "card_expiry_year": 2028
    }
  }
}

{
  "success": false,
  "error": "Transaction not found."
}

curl -X POST https://gateway.circoflows.com/api/v1/hosted/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Firstname",
    "last_name": "Lastname",
    "line1": "Address",
    "country": "US",
    "state": "TX",
    "city": "Dallas",
    "postal_code": "123456",
    "ip_address": "15.6.48.247",
    "email": "test@gmail.com",
    "phone": "+19876549872",
    "amount": "10",
    "currency": "USD",
    "return_url": "https://yoursite.com/return",
    "webhook_url": "https://yoursite.com/webhook",
    "merchant_transaction_id": "MRF-156"
  }'

{
  "first_name": "Firstname",
  "last_name": "Lastname",
  "line1": "Address",
  "country": "US",
  "state": "TX",
  "city": "Dallas",
  "postal_code": "123456",
  "ip_address": "15.6.48.247",
  "email": "test@gmail.com",
  "phone": "+19876549872",
  "amount": "10",
  "currency": "USD",
  "return_url": "https://yoursite.com/return",
  "webhook_url": "https://yoursite.com/webhook",
  "merchant_transaction_id": "MRF-156"
}

{
  "status": "card_url",
  "card_url": "https://gateway.circoflows.com/v1/hosted/card/input/ZEhodVh6Uk5UMXBHTTBKQmRVWjNTSFoyUW1ZPQ==",
  "reason": "Redirect to card_url.",
  "merchant_transaction_id": "MRF-156",
  "transaction_id": "txn_4MOZF3BAuFwHvvBf"
}

curl -X POST https://gateway.circoflows.com/api/v1/test/hosted/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Firstname",
    "last_name": "Lastname",
    "line1": "Address",
    "country": "US",
    "state": "TX",
    "city": "Dallas",
    "postal_code": "123456",
    "ip_address": "15.6.48.247",
    "email": "test@gmail.com",
    "phone": "+19876549872",
    "amount": "10",
    "currency": "USD",
    "return_url": "https://yoursite.com/return",
    "webhook_url": "https://webhook.site/your-webhook-url",
    "merchant_transaction_id": "MRF-150"
  }'

public function createHostedPayment(Request $request)
{
    $apiKey = config('payment.api_key');
    $baseUrl = config('payment.base_url'); // https://gateway.circoflows.com

    $payload = [
        'first_name' => $request->first_name,
        'last_name' => $request->last_name,
        'email' => $request->email,
        'phone' => $request->phone,
        'line1' => $request->address,
        'city' => $request->city,
        'state' => $request->state,
        'postal_code' => $request->postal_code,
        'country' => $request->country,
        'ip_address' => $request->ip(),
        'amount' => $request->amount,
        'currency' => 'USD',
        'merchant_transaction_id' => 'ORDER-' . uniqid(),
        'return_url' => route('payment.return'),
        'webhook_url' => route('payment.webhook'),
    ];

    $response = Http::withHeaders([
        'Authorization' => 'Bearer ' . $apiKey,
        'Content-Type' => 'application/json',
    ])->post($baseUrl . '/api/v1/hosted/create', $payload);

    $data = $response->json();

    if ($data['status'] === 'card_url') {
        // Store transaction_id for later reference
        session(['transaction_id' => $data['transaction_id']]);

        // Redirect customer to the hosted card input page
        return redirect()->away($data['card_url']);
    }

    // Handle error
    return back()->with('error', $data['reason'] ?? 'Payment initialization failed');
}