Card Payments Overview

1. Your app calls POST /api/v1/checkout with amount + customer details
2. RohoPay creates a pending order and returns a payment_url
3. Redirect the customer's browser to payment_url
4. The customer enters their card and completes payment on the hosted page
5. They're redirected back to your return_url (provisional UX hint only)
6. RohoPay's webhook confirms the definitive status and credits your wallet

POST /api/v1/checkout
Content-Type: application/json

curl -X POST https://api.rohopay.com/api/v1/checkout \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "live_YOUR_KEY",
    "amount": 75000,
    "currency": "UGX",
    "customer_name": "Jane Mukasa",
    "customer_email": "jane@example.com",
    "description": "Premium subscription",
    "return_url": "https://your-app.com/payment/return",
    "card_number": "5531886652142950",
    "card_expiry": "09/32",
    "card_cvv": "564"
  }'

const res = await fetch("https://api.rohopay.com/api/v1/checkout", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: process.env.ROHOPAY_API_KEY,
    amount: 75000,
    currency: "UGX",
    customer_name: "Jane Mukasa",
    customer_email: "jane@example.com",
    description: "Premium subscription",
    return_url: "https://your-app.com/payment/return",
    card_number: "5531886652142950",
    card_expiry: "09/32",
    card_cvv: "564",
  }),
});
const { data } = await res.json();

// Full browser redirect — there is no inline/embedded completion step.
window.location.href = data.payment_url;

import httpx, os

def initiate_card_payment(amount: int) -> dict:
    res = httpx.post(
        "https://api.rohopay.com/api/v1/checkout",
        json={
            "api_key": os.environ["ROHOPAY_API_KEY"],
            "amount": amount,
            "currency": "UGX",
            "customer_name": "Jane Mukasa",
            "customer_email": "jane@example.com",
            "return_url": "https://your-app.com/payment/return",
            "card_number": "5531886652142950",
            "card_expiry": "09/32",
            "card_cvv": "564",
        },
    )
    res.raise_for_status()
    return res.json()["data"]  # redirect the browser to data["payment_url"]

{
  "success": true,
  "data": {
    "transaction_id": "01j5m6n7p8q9r0s1t2u3vwxy",
    "reference": "ref_card001",
    "status": "pending",
    "amount": 75000,
    "currency": "UGX",
    "commission": 750,
    "provider": "rohopay",
    "net_amount": 74250,
    "payment_url": "https://checkout.example/pay/abc123"
  },
  "message": "Checkout initiated"
}

https://your-app.com/payment/return?reference=ref_card001&status=successful

// In your /payment/return route
export default async function CheckoutReturn({ searchParams }) {
  const ref = searchParams.reference;
  if (!ref) return <ErrorPage />;

  // Poll until the webhook has confirmed the real status.
  let status = "pending";
  for (let i = 0; i < 12 && status === "pending"; i++) {
    await new Promise(r => setTimeout(r, 2500));
    const res = await fetch(`https://api.rohopay.com/api/v1/transactions/${ref}`, {
      headers: { Authorization: `Bearer ${process.env.ROHOPAY_API_KEY}` },
    });
    status = (await res.json()).data.status;
  }

  return status === "successful" ? <SuccessPage /> : <FailurePage />;
}