TagPayTagPay

Getting started

Quickstart

Take your first TagPay payment in 5 minutes. Sandbox mode is free — no business verification, no waiting. Real cards aren't charged.

1. Sign up + grab your keys

Create an account, then open Developers → API keys. You'll see two sandbox keys:

  • pk_test_* — public, safe to expose in your frontend.
  • sk_test_* — secret, server-side only. Treat it like a password.

Set the secret key as an environment variable:

export TAGPAY_SECRET_KEY=sk_test_your_key_here

2. Install an SDK (or use curl)

Pick your stack:

# Node.js
npm install @tagpay/node
# Python
pip install tagpay
# PHP
composer require tagpay/tagpay-php
# Ruby
gem install tagpay
# Go
go get github.com/tagpayHQ/tagpay-go

3. Create your first charge

Amounts are in kobo. NGN 5,000.00 is 500000.

import TagPay from '@tagpay/node';
const tagpay = new TagPay(process.env.TAGPAY_SECRET_KEY);
const charge = await tagpay.charges.create({
  amount: 500000,
  reference: 'ord_1184',
  customer_email: '[email protected]',
});
console.log(charge.payment_url);
// -> https://checkout.tagpay.ng/pay?sessionKey=cs_4f2a8c1b3d5e7f90a1b2c3d4e5f60718

4. Redirect the customer

Send the customer to charge.payment_url. They'll see the hosted page, complete payment via card/transfer/USSD, then bounce back to your callback_url.

In sandbox, use the test card 4084 0840 8408 4081 with any future expiry and any CVV — it always succeeds.

5. Verify the result

const result = await tagpay.charges.verify('ord_1184');
if (result.status === 'success') {
  // Fulfill the order
  await orders.markPaid(result.reference);
}

6. (Optional) Receive a webhook

For async flows (e.g. bank transfers, which complete out-of-band), configure a webhook URL in Developers → Webhooks. TagPay POSTs a JSON event — for a bank transfer this is charge.success once the customer's payment lands — to your URL with a signed x-tagpay-signature header. See Webhooks for the full handler pattern.

What's next