GlobalPay.bt

API Reference

Complete reference for the GlobalPay.bt API.

Base URL

https://api.gopay.bt

Authentication

All API requests require authentication using Bearer tokens. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Learn more about Authentication.

Rate Limiting

API requests are limited to:

  • 1000 requests per hour for standard plans
  • 5000 requests per hour for enterprise plans

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000

Pagination

List endpoints support pagination using limit and offset parameters:

GET /api/invoices?limit=20&offset=40

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 40,
    "hasMore": true
  }
}

Error Handling

The API uses standard HTTP response codes:

| Code | Meaning | |------|---------| | 200 | Success | | 201 | Created | | 400 | Bad Request - Invalid parameters | | 401 | Unauthorized - Invalid API key | | 403 | Forbidden - Insufficient permissions | | 404 | Not Found - Resource doesn't exist | | 429 | Too Many Requests - Rate limit exceeded | | 500 | Internal Server Error |

Error responses include details:

{
  "error": {
    "message": "Invalid customer ID",
    "type": "validation_error",
    "code": "invalid_customer",
    "field": "customerId"
  }
}

Core Resources

GET/api/invoices

List all invoices

POST/api/invoices

Create a new invoice

GET/api/payments

List all payments

POST/api/refunds

Create a refund

Endpoints by Resource

Invoices

Create, retrieve, and manage invoices.

Payments

Process and track payments.

Refunds

Process refunds for completed payments.

Webhooks

Configure webhook endpoints to receive real-time notifications.

Currency Handling

All monetary amounts are in the smallest currency unit (cents/paisa):

{
  "amount": 10000,  // 100.00 BTN
  "currency": "BTN"
}

Supported currencies:

  • BTN (Bhutanese Ngultrum)
  • USD (US Dollar)
  • INR (Indian Rupee)

Idempotency

Prevent duplicate requests by including an idempotency key:

curl -X POST https://api.gopay.bt/api/invoices \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Idempotency-Key: unique-key-123" \\
  -H "Content-Type: application/json"

Webhooks

Receive real-time notifications for events:

  • invoice.created
  • invoice.paid
  • payment.completed
  • payment.failed
  • refund.processed

Learn more about Webhooks

SDKs and Libraries

Official SDKs coming soon for Node.js, Python, PHP, and more.

Testing

Use test API keys and test card numbers to verify your integration without processing real payments.

View testing guide

Need Help?