Hosted Checkout Flow: Lets you redirect customers to UMVA's hosted payment page where they can pay via card, mobile money, crypto, or UMVA account balance. This flow is implemented via web routes, not under the /api/server-api-payment prefix.

Step 1 — Initiate Hosted Payment:

Endpoint: POST https://umva.net/payment/initiate (web endpoint, not under /api/)

Parameters (form or JSON body):

• public_key (required, string): Merchant Public API Key (Live or Test).
• identifier (required, string): Your unique reference (max 20 characters).
• currency (required, string): e.g. USD, RWF.
• amount (required, number): Amount to charge.
• details (required, string): Short description (max 100 characters).
• ipn_url (required, string): URL to receive payment notification.
• cancel_url (required, string): Redirect URL if the user cancels.
• success_url (required, string): Redirect URL after success.
• customer_name (optional, string).
• customer_email (optional, string).
• customer (optional, object): { first_name, last_name, email, mobile }.
• gateway_methods (optional, array): Restrict to specific gateways.
• site_logo (optional, string): URL of your logo.
• checkout_theme (optional, string): "dark" or "light".

Example Request:

curl -X POST "https://umva.net/payment/initiate" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d "{
    \"public_key\": \"PUB-LIVE-XXX\",
    \"identifier\": \"ORD-12345\",
    \"currency\": \"USD\",
    \"amount\": 50,
    \"details\": \"Order #12345\",
    \"ipn_url\": \"https://yoursite.com/ipn\",
    \"cancel_url\": \"https://yoursite.com/cancel\",
    \"success_url\": \"https://yoursite.com/success\"
  }"

Success Response Example (HTTP 200):

{
  "success": "ok",
  "message": "Payment Initiated. Redirect to url",
  "url": "https://umva.net/initiate/payment/auth/view/ENCRYPTED_PAYMENT_ID"
}

Step 2 — Redirect Customer to Hosted URL:

Redirect the customer to the url from the response above. The underlying routes are:

• Live: GET https://umva.net/initiate/payment/auth/view/{payment_id}
• Test: GET https://umva.net/test/initiate/payment/auth/view/{payment_id}

Here {payment_id} is the encrypted transaction reference contained inside the url value. Do not construct this value yourself; always redirect to the exact url returned by /payment/initiate.

On the hosted checkout page, the customer can:

• Verify their identity (e.g., OTP).
• Choose a payment method (card, mobile money, crypto, UMVA account balance).
• Complete payment and be redirected to success_url or cancel_url.

Your ipn_url receives the confirmation. For account-balance or hosted payments, the IPN payload typically has payment_type such as "hosted" and follows the same generic IPN format shown in the IPN Validation section.