OasisPay
Start Building

OasisPay Docs

Build with OasisPay

Create payments, issue virtual accounts, verify signed webhooks, and test safely before going live.

Getting Started

Use your secret key in the `Authorization` header. For every create request, send an `Idempotency-Key` so safe retries do not create duplicates.

curl https://api.oasispayhq.com/api/v1/payments \
  -H "Authorization: Bearer osk_test_xxx" \
  -H "Idempotency-Key: order_1001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": { "amount": 5000, "currency": "NGN" },
    "customer": { "email": "[email protected]" },
    "paymentMethod": "bank_transfer"
  }'

API Reference

POST/api/v1/paymentsCreate a payment and return checkout or transfer instructions.
POST/api/v1/virtual-accounts/reservedCreate a reusable customer virtual account.
POST/api/v1/virtual-accounts/dynamicCreate an amount-bound virtual account.
POST/api/v1/beneficiariesCreate and verify a payout recipient.
POST/api/v1/payoutsInitiate a payout to a saved beneficiary.

Payment Creation

Create a payment with an amount, customer, and payment method. OasisPay returns instructions for the customer to complete the payment.

JavaScript
await fetch("https://api.oasispayhq.com/api/v1/payments", {
  method: "POST",
  headers: {
    Authorization: "Bearer osk_test_xxx",
    "Content-Type": "application/json",
    "Idempotency-Key": "order_1001"
  },
  body: JSON.stringify({
    amount: { amount: 5000, currency: "NGN" },
    customer: { email: "[email protected]" },
    paymentMethod: "bank_transfer"
  })
});

Virtual Accounts

Use dynamic virtual accounts for one payment, or reserved virtual accounts for reusable customer collections.

Dynamic Virtual Account
await fetch("https://api.oasispayhq.com/api/v1/virtual-accounts/dynamic", {
  method: "POST",
  headers: {
    Authorization: "Bearer osk_test_xxx",
    "Content-Type": "application/json",
    "Idempotency-Key": "va_1001"
  },
  body: JSON.stringify({
    amount: 5000,
    currency: "NGN",
    customer: { email: "[email protected]" }
  })
});

Webhooks

OasisPay sends `X-OasisPay-Signature`, `X-OasisPay-Timestamp`, and `X-OasisPay-Event`. Verify `HMAC_SHA256(timestamp + "." + rawBody, webhookSecret)`.

Node.js Verification
import crypto from "crypto";

function verifyWebhook(rawBody, headers, secret) {
  const timestamp = headers["x-oasispay-timestamp"];
  const signature = headers["x-oasispay-signature"];
  const expected = crypto
    .createHmac("sha256", secret)
    .update(timestamp + "." + rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
payment.successpayment.failedvirtual_account.credittransaction.createdsettlement.completedpayout.successfulpayout.failed

Errors

Every API error includes a request ID. Use it when checking API logs or contacting support.

{
  "statusCode": 401,
  "message": "Invalid API key.",
  "requestId": "req_xxx",
  "path": "/api/v1/payments",
  "timestamp": "2026-06-03T12:00:00.000Z"
}

SDKs And Language Examples

PHP
$client->payments->create([
  "amount" => ["amount" => 5000, "currency" => "NGN"],
  "customer" => ["email" => "[email protected]"]
]);
Python
client.payments.create(
  amount={"amount": 5000, "currency": "NGN"},
  customer={"email": "[email protected]"}
)
Laravel
OasisPay::payments()->create([
  "amount" => ["amount" => 5000, "currency" => "NGN"],
  "customer" => ["email" => "[email protected]"]
]);
JavaScript
await client.payments.create({
  amount: { amount: 5000, currency: "NGN" },
  customer: { email: "[email protected]" }
});

Testing

Use `osk_test_` keys for sandbox calls. Send stable idempotency keys when retrying POST requests.

Headers:
Authorization: Bearer osk_test_xxx
Idempotency-Key: your_unique_operation_id

Test webhook endpoints from:
/dashboard/developers/webhooks