VTU API
Get API keys
Payment Gateway

Create a payment

Creates a payment and returns the checkout_url to send your customer to.

POST https://api.paybeta.ng/api/v1/payments

Send the customer to the returned checkout_url (redirect), or open it as a popup with new PaybetaPop().resumeTransaction(id), using the payment's id.

  • mode decides whether this is a test payment (no real money) or a live one. See Test mode.
  • Sending the same reference and amount again returns the existing payment (200 OK), so a timed-out request is safe to retry. The same reference with another amount is refused (409 Conflict).
  • Keep the id or your reference to verify the payment later.

More examples (pick them in the Request menu): a payment where the customer pays the fee, a Paybeta wallet-only payment, and a live payment.

The payment object

Field Description
id Paybeta's id for the payment (GTW-…).
reference Your reference.
status pending, successful, failed or expired.
amount The amount you asked for, in naira.
fee Paybeta's fee.
pass_charge Whether the fee is added on top for the customer.
charge_amount What the customer pays: amount, or amount + fee with pass_charge.
amount_paid What the customer paid, once paid; null before.
merchant_amount What you receive.
mode / livemode test or live.
channel How it was paid (card, transfer, bank, ussd, wallet); null until paid.
customer, description, metadata As you sent them.
recurring, authorization Saved cards; not available yet.
checkout_url The payment page.
failure_reason Why the last attempt was declined, if it was.
expires_at, paid_at, created_at Times (ISO 8601, West Africa Time, +01:00).
Send your secret key in the P-API-KEY header. Keep it on your server, never in an app or browser.

Body (JSON)

  • mode string Required

    test (sandbox, no real money) or live.

    Example: test
  • reference string Required

    Your unique reference for this payment. Reusing it with the same amount returns the existing payment.

    Example: ORDER-1001
  • amount number Required

    In naira. Minimum ₦100.

    Example: 5000
  • currency string Optional

    NGN (the only currency).

    Example: NGN
  • customer object Required

    Who is paying.

  • customer.email string Required

    The customer's email.

    Example: ada@example.com
  • customer.name string Optional

    The customer's name.

    Example: Ada Lovelace
  • customer.phone string Optional

    The customer's phone number.

    Example: 08012345678
  • description string Optional

    Shown to the customer on the payment page.

    Example: Pro plan · monthly
  • redirect_url string Optional

    Where the customer goes after paying (https).

    Example: https://shop.example.com/thanks
  • webhook_url string Optional

    Where the webhook goes (public https). Without it, the one saved in the API console is used.

    Example: https://shop.example.com/webhooks/paybeta
  • channels string Optional

    The payment options to offer: card, transfer, bank, ussd, wallet. Options switched off for your account are left out.

    Example: ["card","transfer", "bank", "wallet", "ussd"]
  • pass_charge boolean Optional

    true adds Paybeta's fee on top for the customer, so you receive the full amount. Without it, your console default applies.

    Example: false
  • metadata object Optional

    Your own data (up to 4KB), returned on the payment and its webhook.

    Example: {"cart_id":9}
  • expires_in integer Optional

    Minutes until the payment page expires: 5 to 10080. Default 60.

    Example: 60
  • recurring boolean Optional

    true saves the card for later charges (card only). Not available yet.

    Example: false

Responses

  • 201Created
  • 201Customer pays the fee
  • 200Same reference again
  • 400Validation error
  • 409Same reference, different amount
Request 
curl --request POST \
  --url 'https://api.paybeta.ng/api/v1/payments' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'P-API-KEY: YOUR_SECRET_KEY' \
  --data '{
  "mode": "test",
  "reference": "ORDER-{{$timestamp}}",
  "amount": 5000,
  "currency": "NGN",
  "description": "Pro plan · monthly",
  "customer": {
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "phone": "08012345678"
  },
  "redirect_url": "https://shop.example.com/thanks",
  "webhook_url": "https://shop.example.com/webhooks/paybeta",
  "channels": ["card", "transfer", "bank", "ussd", "wallet"],
  "pass_charge": false,
  "metadata": {
    "cart_id": 9
  },
  "expires_in": 60
}'
Response 
{
  "status": "successful",
  "message": "Payment created",
  "data": {
    "id": "GTW-K3J7Q2M9X4ZP8L1N5R6T0V2B3C4D",
    "reference": "ORDER-1001",
    "status": "pending",
    "amount": 5000,
    "fee": 70,
    "pass_charge": false,
    "charge_amount": 5000,
    "amount_paid": null,
    "merchant_amount": 4930,
    "mode": "test",
    "livemode": false,
    "currency": "NGN",
    "channel": null,
    "description": "Pro plan · monthly",
    "customer": {
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "phone": "08012345678"
    },
    "metadata": {
      "cart_id": 9
    },
    "recurring": false,
    "authorization": null,
    "checkout_url": "https://checkout.paybeta.ng/pay/GTW-K3J7Q2M9X4ZP8L1N5R6T0V2B3C4D",
    "provider": "squad",
    "provider_reference": null,
    "failure_reason": null,
    "expires_at": "2026-10-30T13:00:00+01:00",
    "paid_at": null,
    "created_at": "2026-10-30T12:00:00+01:00"
  }
}