OrbitWeb Studio Paystack API

Access requirements

Before integrating, the external platform must receive a private Bearer token from OrbitWeb Studio and register its approved success URL. The token must be stored only on the platform’s server.

Initialize your first payment

Send a JSON request from your server. Amounts use the main currency unit: for example, 1000 is converted internally to 100000 subunits.

curl --request POST 'https://orbitwebstudioafrica.com/api/payments/initialize' \
  --header 'Authorization: Bearer YOUR_PRIVATE_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "customer@example.com",
    "amount": 1000,
    "currency": "MZN",
    "mode": "test",
    "order": "d26f47a0-bde8-43d9-833b-b5dc72f2134c",
    "payment": "d03f50bd-3c9b-4a08-a6d6-27409211a85e",
    "customer": {
      "name": "Customer Name",
      "phone": "+258840000000"
    },
    "metadata": {
      "source": "your-platform"
    }
  }'

Initialize payment

Required headers

Charge a consented card reference

This server-to-server endpoint charges a reusable Paystack authorization previously captured from a successful, explicitly consented payment. The private authorization code is never returned.

curl --request POST 'https://orbitwebstudioafrica.com/api/payments/one-click' \
  --header 'Authorization: Bearer YOUR_PRIVATE_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "customer@example.com",
    "amount": 1000,
    "currency": "ZAR",
    "order": "d26f47a0-bde8-43d9-833b-b5dc72f2134c",
    "payment": "d03f50bd-3c9b-4a08-a6d6-27409211a85e",
    "instrument": "saved-instrument-uuid",
    "external_customer_id": "platform-customer-uuid",
    "mode": "test"
  }'

Read payment status

After the browser returns to your platform, confirm the payment from your backend before changing local order state.

Use the same private Bearer token. A successful response includes the original order and payment UUIDs, Paystack reference, amount, currency, status and verification time.

{
  "success": true,
  "data": {
    "order": "d26f47a0-bde8-43d9-833b-b5dc72f2134c",
    "payment": "d03f50bd-3c9b-4a08-a6d6-27409211a85e",
    "reference": "d03f50bd-3c9b-4a08-a6d6-27409211a85e",
    "amount": "1000.00",
    "currency": "MZN",
    "status": "success",
    "verified_at": "2026-07-29T10:00:00+00:00"
  }
}

Parameters

All required values are validated before any request is sent to Paystack.

Successful response

A successful initialization returns HTTP 200. Redirect the customer’s browser to authorization_url. Do not redirect directly to your own success page.

{
  "success": true,
  "data": {
    "authorization_url": "https://checkout.paystack.com/access-code",
    "reference": "d03f50bd-3c9b-4a08-a6d6-27409211a85e"
  }
}

What to do next

1. Store the responseAssociate the returned reference and authorization URL with your order.
2. Open PaystackRedirect the customer to the exact authorization_url.
3. Wait for confirmationPaystack notifies OrbitWeb Studio through a signed server-to-server webhook.
4. Reconcile the paymentOrbitWeb Studio notifies your configured backend URL with the verified order and payment UUIDs.

HTTP status codes

Validation error example

{
  "message": "The payment field must be a valid UUID.",
  "errors": {
    "payment": [
      "The payment field must be a valid UUID."
    ]
  }
}

Callback and final redirect

The Paystack callback belongs to OrbitWeb Studio and is included automatically during initialization. A signed Paystack webhook confirms successful payments even if the customer never returns in the browser. External platforms must not call either endpoint manually and must not send their own callback URL in the payload.

Successful final redirect

Failed transaction redirect

The final success URL is registered in the OrbitWeb Studio API configuration. It is intentionally not accepted in each request, preventing an attacker from injecting an arbitrary redirect destination.

Integration checklist

• Use HTTPSSend requests only to the official HTTPS API address.
• Protect the Bearer tokenStore it in server-side secrets or environment variables.
• Generate real UUIDsNever use sequential identifiers for order or payment.
• Do not trust browser redirectsUpdate local payment state only through your trusted server-side workflow.
• Keep references uniqueEvery payment attempt requires a new payment UUID.
• Do not log secretsRedact authorization headers from application and proxy logs.