GlobalPay.bt

Invoices API

Create, retrieve, and manage invoices.

The Invoice Object

{
  "id": "inv_1234567890",
  "customerId": "cust_abc123",
  "amount": 10000,
  "currency": "BTN",
  "status": "pending",
  "description": "Monthly subscription",
  "dueDate": "2025-12-31T23:59:59Z",
  "paymentUrl": "https://gopay.bt/pay/inv_1234567890",
  "createdAt": "2025-12-01T00:00:00Z",
  "updatedAt": "2025-12-01T00:00:00Z"
}

Attributes

| Attribute | Type | Description | |-----------|------|-------------| | id | string | Unique invoice identifier | | customerId | string | Customer who will pay this invoice | | amount | integer | Amount in smallest currency unit (cents/paisa) | | currency | string | Three-letter ISO currency code (BTN, USD, INR) | | status | string | Invoice status: pending, paid, overdue, cancelled | | description | string | Description of the invoice | | dueDate | string | ISO 8601 datetime when payment is due | | paymentUrl | string | URL where customer can pay | | createdAt | string | ISO 8601 datetime of creation | | updatedAt | string | ISO 8601 datetime of last update |

List Invoices

GET/api/invoices

Retrieve a list of invoices

Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | limit | integer | No | Number of results (1-100, default: 20) | | offset | integer | No | Number of results to skip (default: 0) | | status | string | No | Filter by status: pending, paid, overdue, cancelled | | customerId | string | No | Filter by customer ID |

Example Request

curl -X GET "https://api.gopay.bt/api/invoices?limit=10&status=pending" \\
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "inv_1234567890",
      "customerId": "cust_abc123",
      "amount": 10000,
      "currency": "BTN",
      "status": "pending",
      "description": "Monthly subscription",
      "dueDate": "2025-12-31T23:59:59Z",
      "paymentUrl": "https://gopay.bt/pay/inv_1234567890",
      "createdAt": "2025-12-01T00:00:00Z",
      "updatedAt": "2025-12-01T00:00:00Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

Create Invoice

POST/api/invoices

Create a new invoice

Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | customerId | string | Yes | Customer ID or email | | amount | integer | Yes | Amount in smallest currency unit | | currency | string | Yes | Currency code (BTN, USD, INR) | | description | string | Yes | Invoice description | | dueDate | string | No | ISO 8601 datetime (default: 30 days) |

Example Request

curl -X POST https://api.gopay.bt/api/invoices \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "customerId": "cust_abc123",
  "amount": 10000,
  "currency": "BTN",
  "description": "Monthly subscription",
  "dueDate": "2025-12-31T23:59:59Z"
}'

Example Response

{
  "id": "inv_1234567890",
  "customerId": "cust_abc123",
  "amount": 10000,
  "currency": "BTN",
  "status": "pending",
  "description": "Monthly subscription",
  "dueDate": "2025-12-31T23:59:59Z",
  "paymentUrl": "https://gopay.bt/pay/inv_1234567890",
  "createdAt": "2025-12-01T00:00:00Z",
  "updatedAt": "2025-12-01T00:00:00Z"
}

Retrieve Invoice

GET/api/invoices/:id

Retrieve a specific invoice

Example Request

curl -X GET https://api.gopay.bt/api/invoices/inv_1234567890 \\
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "id": "inv_1234567890",
  "customerId": "cust_abc123",
  "amount": 10000,
  "currency": "BTN",
  "status": "pending",
  "description": "Monthly subscription",
  "dueDate": "2025-12-31T23:59:59Z",
  "paymentUrl": "https://gopay.bt/pay/inv_1234567890",
  "createdAt": "2025-12-01T00:00:00Z",
  "updatedAt": "2025-12-01T00:00:00Z"
}

Update Invoice

PATCH/api/invoices/:id

Update an existing invoice

You can only update invoices with status pending. Paid or cancelled invoices cannot be modified.

Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | amount | integer | No | New amount | | description | string | No | New description | | dueDate | string | No | New due date |

Example Request

curl -X PATCH https://api.gopay.bt/api/invoices/inv_1234567890 \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "amount": 15000,
    "description": "Updated subscription amount"
  }'

Delete Invoice

DELETE/api/invoices/:id

Cancel an invoice

This action cannot be undone. The invoice status will be set to cancelled.

Example Request

curl -X DELETE https://api.gopay.bt/api/invoices/inv_1234567890 \\
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "id": "inv_1234567890",
  "status": "cancelled",
  "deletedAt": "2025-12-11T10:30:00Z"
}

Next Steps