API Documentation - SecurePay

Overview

The SecurePay API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL

All API requests should be made to the following base URL:

HTTPS

                        https://preview.royalstrides.com/api/v1

Authentication

Authentication is performed via API Keys. You can find your API keys in the Merchant Dashboard under Settings > API Keys.

Always keep your Secret keys private. Do not share them or use them in client-side code (browsers, mobile apps).

Include your API key in the Authorization header of all requests:

Header

                        Authorization: Bearer pk_live_your_key_here

Request Signatures

For enhanced security, all write requests (POST, PUT, DELETE) must be signed using your Secret Key. This ensures the request was not tampered with during transit.

Header	Description
`X-Timestamp`	Current Unix timestamp in seconds. Requests older than 5 minutes will be rejected.
`X-Signature`	HMAC-SHA256 hash of the request body using your Secret Key.

Payment Gateways

Retrieve a list of payment gateways available for your account.

GET /gateways

JSON Response

{
  "success": true,
  "data": [
    {
      "slug": "stripe",
      "name": "Stripe",
      "currencies": ["USD", "EUR"],
      "logo": "https://..."
    }
  ]
}

Initialize Payment

Create a new transaction and get a payment URL for your customer.

POST /transactions

Parameter	Type	Required	Description
`amount`	numeric	Required	The amount to charge (e.g., 99.99).
`currency`	string	Required	3-letter ISO currency code (e.g., USD, NGN).
`customer[email]`	string	Required	The email address of the customer.
`gateway`	string	Optional	Specific gateway slug. If omitted, the best gateway will be auto-selected.

Refunds

Refund a successful transaction. You can perform full or partial refunds.

POST /transactions/{uuid}/refund

Parameter	Type	Description
`amount`	numeric	Amount to refund. Defaults to full remaining amount if omitted.
`reason`	string	Reason for the refund (internal use).

Subscriptions & Plans

Our API supports powerful recurring billing logic.

1. Create a Plan

POST /plans

2. Create Subscription

POST /subscriptions

Requires a payment_token generated by our SDKs (e.g., Stripe Elements token).

Webhooks

Webhooks allow you to receive real-time notifications about events in your account, such as successful payments or failed renewals.

Security: Always verify the webhook signature using your Webhook Secret to ensure the payload is authentic.

Verification Code (PHP)

$signature = $_SERVER['HTTP_X_SIGNATURE'];
$payload = file_get_contents('php://input');
$expected = hash_hmac('sha256', $payload, $webhookSecret);

if (hash_equals($expected, $signature)) {
    // Valid webhook
}

Error Handling

We use standard HTTP response codes to indicate the success or failure of an API request.

Code	Description
`200`	Success.
`201`	Created successfully.
`400`	Bad Request. Check your parameters.
`401`	Unauthorized. Invalid API key.
`422`	Validation Error. Some fields are invalid.
`500`	Internal Server Error. Something went wrong on our end.

Developer Documentation