Accept Gift Card Payments

Integrate Paygivo into your platform. Verify, charge, and refund gift cards with a simple REST API. Start accepting gift card payments in minutes.

Get Started View Endpoints

Getting Started

Three steps to start processing gift card payments.

Register as a Merchant

Create a merchant account via the API and receive your API key and secret.

Get Your API Key

Store the API key securely. You will send it as the x-api-key header on every request.

Integrate & Charge

Verify gift card balances, charge cards, and process refunds programmatically.

Register via API

bash

curl -X POST https://api.paygivo.com/merchants/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Store",
    "email": "dev@mystore.com",
    "website": "https://mystore.com"
  }'

# Response:
# {
#   "id": "merchant_uuid",
#   "apiKey": "64-char-hex-key",
#   "apiSecret": "64-char-hex-secret",
#   "message": "Store your API secret securely. It will not be shown again."
# }

Authentication

All merchant API endpoints require the x-api-key header. Include your API key with every request.

http

GET /api/v1/merchant/balance HTTP/1.1
Host: api.paygivo.com
x-api-key: YOUR_API_KEY
Content-Type: application/json

Important: Keep your API key and secret secure. Never expose them in client-side code or public repositories. Regenerate credentials immediately if compromised via POST /merchants/regenerate-keys.

API Endpoints

Base URL: https://api.paygivo.com

Code Examples

Quick-start snippets for common use cases.

bash

# Verify a gift card
curl -X POST https://api.paygivo.com/api/v1/merchant/verify-card \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "A1B2-C3D4-E5F6-G7H8"}'

# Charge a gift card
curl -X POST https://api.paygivo.com/api/v1/merchant/charge \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "A1B2-C3D4-E5F6-G7H8",
    "amount": 2500,
    "reference": "order-12345",
    "description": "Purchase at My Store"
  }'

# Refund a charge
curl -X POST https://api.paygivo.com/api/v1/merchant/refund \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transactionId": "txn_uuid", "amount": 1000}'

# Look up a transaction
curl https://api.paygivo.com/api/v1/merchant/transaction/order-12345 \
  -H "x-api-key: YOUR_API_KEY"

Error Codes

The API uses standard HTTP status codes. Error responses include a message field with a human-readable explanation.

Code	Meaning	Description
400	Bad Request	Invalid parameters or insufficient balance
401	Unauthorized	Missing or invalid API key
404	Not Found	Gift card or transaction not found
409	Conflict	Duplicate transaction reference
429	Too Many Requests	Rate limit exceeded (60 req/min)
500	Internal Server Error	Unexpected server error

Rate Limits

To ensure fair usage, the API enforces the following rate limits:

Requests per minute

1,000

Requests per hour

10,000

Requests per day

When you exceed a rate limit, the API responds with a 429 Too Many Requests status. The response includes a Retry-After header indicating how many seconds to wait before retrying.

Webhooks Coming Soon

Receive real-time notifications when events occur on your merchant account. Configure a webhook URL during registration or update it via the API.

json

{
  "event": "charge.completed",
  "data": {
    "transactionId": "txn_uuid",
    "reference": "order-12345",
    "amount": 2500,
    "currency": "NGN",
    "status": "COMPLETED",
    "merchantId": "merchant_uuid",
    "timestamp": "2026-04-08T12:00:00.000Z"
  }
}

Webhook payloads are signed with your API secret using HMAC-SHA256. Verify the x-paygivo-signature header to ensure authenticity.

Ready to Integrate?

Contact Sales Read the Docs