VeloraPay developer documentation

1. Create or select the integration

   Use the Merchant Dashboard to create the container for the app or system that will connect to VeloraPay.

2. Create the test API key

   API keys are scoped to one integration. Copy the one-time key into your backend secret manager and use it only from your server.

3. Add the webhook endpoint

   Register your HTTPS receiver in the Merchant Dashboard. Copy the one-time signing secret into your webhook verifier before accepting payment events.

4. Use the API key from your backend

   After dashboard setup, call the payment APIs below with Authorization: Bearer ak_test_example in staging. Do not expose merchant API keys in browser or mobile clients.

1. Record the invoice line items

   Use the same invoice_ref when you create the checkout session. Invoice lines help the payer recognize the bill and help your finance team settle collections by service code.

   Request Copy

   curl https://api.staging.velorapay.com/api/v1/invoice-lines \
     -H "Authorization: Bearer ak_test_example" \
     -H "Idempotency-Key: invoice-EPA-2026-001" \
     -H "Content-Type: application/json" \
     -d '{
       "invoice_ref": "EPA-2026-001",
       "currency": "GHS",
       "lines": [
         { "code": "EPA-PERMIT", "name": "Permit fee", "amount_minor": 300000 },
         { "code": "EPA-LEVY", "name": "Environmental levy", "amount_minor": 7038 }
       ]
     }'

   Expected response Copy

   {
     "object": "invoice.line_items",
     "invoice_ref": "EPA-2026-001",
     "ingested": 2,
     "billed_minor": 307038,
     "errors": []
   }

2. Create the checkout session

   The response includes checkout_url. Redirect the payer there, or send the link through your own payment notification flow.

   Node.js Python curl

   Node.js Copy

   const response = await fetch("https://api.staging.velorapay.com/api/v1/sessions", {
     method: "POST",
     headers: {
       "Authorization": "Bearer ak_test_example",
       "Idempotency-Key": "checkout-EPA-2026-001",
       "Content-Type": "application/json"
     },
     body: JSON.stringify({
       invoice_ref: "EPA-2026-001",
       amount_minor: 307038,
       currency: "GHS",
       description: "EPA permit payment",
       customer: { name: "Kwame Asante", email: "kwame@example.com" },
       callback_url: "https://epa.gov.gh/payments/return"
     })
   });
   
   const session = await response.json();
   return session.checkout_url;

   Python Copy

   import requests
   
   response = requests.post(
       "https://api.staging.velorapay.com/api/v1/sessions",
       headers={
           "Authorization": "Bearer ak_test_example",
           "Idempotency-Key": "checkout-EPA-2026-001",
       },
       json={
           "invoice_ref": "EPA-2026-001",
           "amount_minor": 307038,
           "currency": "GHS",
           "description": "EPA permit payment",
           "customer": {"name": "Kwame Asante", "email": "kwame@example.com"},
           "callback_url": "https://epa.gov.gh/payments/return",
       },
       timeout=15,
   )
   response.raise_for_status()
   checkout_url = response.json()["checkout_url"]

   curl Copy

   curl https://api.staging.velorapay.com/api/v1/sessions \
     -H "Authorization: Bearer ak_test_example" \
     -H "Idempotency-Key: checkout-EPA-2026-001" \
     -H "Content-Type: application/json" \
     -d '{
       "invoice_ref": "EPA-2026-001",
       "amount_minor": 307038,
       "currency": "GHS",
       "description": "EPA permit payment",
       "customer": { "name": "Kwame Asante", "email": "kwame@example.com" },
       "callback_url": "https://epa.gov.gh/payments/return"
     }'

   Expected response Copy

   {
     "id": "cs_example",
     "status": "open",
     "amount_minor": 307038,
     "currency": "GHS",
     "invoice_ref": "EPA-2026-001",
     "description": "EPA permit payment",
     "checkout_url": "https://velorapay-checkout-staging-fxzcszzkha-uc.a.run.app/pay/cs_example",
     "expires_at": "2026-06-14T12:30:00Z"
   }

   Set callback_url to your return route and store the VeloraPay session id, invoice_ref, and your order id before redirecting the payer. After checkout completes, VeloraPay can return the payer to EPA's callback URL. EPA must still confirm final state by webhook or server-side session lookup before marking the order paid.

3. Let VeloraPay-hosted checkout collect the payment

   After you redirect the payer to checkout_url, VeloraPay-hosted checkout handles payment-method selection, fee display, Mobile Money prompts, card entry, cash slip creation, and payment collection. Your backend waits for a webhook or session lookup; it does not start payment-method calls.

4. Confirm session status from your backend

   Signed webhooks are the primary fulfilment signal. If EPA needs a fallback lookup after the payer returns, call the merchant session endpoint with the integration API key. This path does not require an attempt_reference.

   Session lookup request Copy

   curl https://api.staging.velorapay.com/api/v1/sessions/cs_example \
     -H "Authorization: Bearer ak_test_example"

   Checkout session response Copy

   {
     "id": "cs_example",
     "status": "pending",
     "amount_minor": 307038,
     "currency": "GHS",
     "invoice_ref": "EPA-2026-001",
     "description": "EPA permit payment",
     "checkout_url": "https://velorapay-checkout-staging-fxzcszzkha-uc.a.run.app/pay/cs_example",
     "expires_at": "2026-06-14T12:30:00Z"
   }

5. Fulfil only after confirmation

   A return to your site is not proof of payment. Fulfil only after the signed webhook or final checkout status confirms the payment amount, currency, invoice reference, and terminal state.

   Safe to fulfil

   checkout.session.completed, terminal success, matching amount, matching currency, and matching invoice reference.

   Do not fulfil

   Pending, failed, expired, amount mismatch, currency mismatch, duplicate event with changed body, or invalid signature.

The full error-code enum is published in the OpenAPI component MerchantErrorCode.

• Staging checkout succeeds and failed/expired cases do not release value.
• Webhook receiver verifies raw-body signatures and dedupes event ids.
• Idempotency keys are used on checkout and invoice-line writes.
• Merchant API keys are stored in a backend secret store.
• Support team can trace an invoice_ref across checkout, webhook, and settlement evidence.