Yoventra Payment Gateway

1. Introduction

Yoventra operates a direct multi-channel payment gateway that allows online businesses to receive payments from their customers. When integrated, payments can be funded via:

2. Merchant Registration

To start accepting payments, register your business at /merchant/register.php. Upon registration, you will receive:

• Multi-currency settlement bank accounts (USD, GHS, NGN, EUR, GBP)
• Test API credentials (pk_test_... and sk_test_...)
• Live API credentials (pk_live_... and sk_live_...)
• Unique HMAC Webhook Signing Secret (whsec_...)

3. API Authentication

We use API keys to authenticate requests. Authenticate server-to-server requests by providing your Secret Key in the Authorization header:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Initializes a transaction session and returns a checkout URL and session token.

{
  "amount": 150.00,
  "currency": "USD",
  "email": "customer@example.com",
  "name": "John Doe",
  "phone": "+1234567890",
  "reference": "ORDER-99120",
  "callback_url": "https://mysite.com/payment/callback",
  "return_url": "https://mysite.com/order/success",
  "description": "Invoice #99120 Payment"
}

{
  "status": true,
  "code": "PAYMENT_INITIALIZED",
  "message": "Payment initialized successfully.",
  "data": {
    "transaction_id": "GW-20260916-A1B2C3D4",
    "merchant_reference": "ORDER-99120",
    "amount": 150.00,
    "currency": "USD",
    "fee": 3.50,
    "net_amount": 146.50,
    "environment": "live",
    "session_id": "cs_live_9f81a7b3c2e5d4...",
    "checkout_url": "https://yoventra.top/checkout/index.php?session=cs_live_...",
    "expires_at": "2026-09-16 05:00:00"
  }
}

Verify payment status directly server-to-server using the gateway reference (GW-...) or your merchant reference.

curl -X GET "https://yoventra.top/api/v1/payment/verify.php?reference=GW-20260916-A1B2C3D4" \
     -H "Authorization: Bearer sk_live_xxxxxx"

{
  "status": true,
  "code": "PAYMENT_VERIFIED",
  "data": {
    "transaction_id": "GW-20260916-A1B2C3D4",
    "merchant_reference": "ORDER-99120",
    "amount": 150.00,
    "currency": "USD",
    "fee": 3.50,
    "net_amount": 146.50,
    "status": "successful",
    "payment_method": "bank_account",
    "paid_at": "2026-09-16 04:32:10",
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe",
      "phone": "+1234567890"
    }
  }
}

7. Embeddable JavaScript Popup SDK

Include our lightweight JavaScript SDK on your checkout page to open a modal payment popup without sending customers off-site:

<script src="https://yoventra.top/sdk/checkout.js"></script>

<script>
function payNow() {
  BankGateway.checkout({
    key: "pk_live_xxxxxxxxxxxxxxxx",
    amount: 150.00,
    currency: "USD",
    reference: "ORDER-99120",
    customer: {
      email: "customer@example.com",
      name: "John Doe",
      phone: "+1234567890"
    },
    callback: function(response) {
      console.log('Payment complete!', response);
      // Verify payment on your backend using /api/v1/payment/verify.php
      window.location.href = '/order/confirmation?ref=' + response.reference;
    },
    onClose: function() {
      console.log('Checkout modal was closed by customer');
    }
  });
}
</script>

8. Webhooks & HMAC Signature Verification

Every successful payment, refund, or failure triggers an HTTP POST request to your configured webhook endpoint. Verify the X-Bank-Signature header using your webhook secret:

<?php
// PHP Webhook Receiver Example
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_BANK_SIGNATURE'] ?? '';
$secret = 'whsec_your_secret_key';

// Verify HMAC-SHA256 signature
$expected = hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = json_decode($payload, true);

if ($event['event'] === 'payment.success') {
    $txId = $event['data']['transaction_id'];
    $orderRef = $event['data']['reference'];
    $amount = $event['data']['amount'];
    // Fulfill order in your database
}

http_response_code(200);
echo json_encode(['received' => true]);
?>

9. Idempotency Keys

To prevent accidental duplicate charges during network timeouts, send an Idempotency-Key header with a unique request UUID. If the same request is retried, the gateway safely returns the cached transaction without charging the customer again.

Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

10. Standard Error Codes