Taxpayer API

Create, retrieve, and manage your own invoices: list invoices, create them (standard, full, or bulk), update or edit them, update status/payment state (including partial payments), and exchange supplier invoices.

text

Base path: /v1/tax-payers

All endpoints require an x-api-key header with your tpk_-prefixed Taxpayer API key — see Authentication. Endpoints that create invoices (Create Invoice, Create Invoice (Full), Create Invoices (Bulk)) additionally require an active subscription and a complete business profile: business address (city, state and country), business email, and your NRS Business ID and NRS Service ID. Sign-up doesn't ask for the email or the city, state and country, and the two IDs are optional there; until the profile is complete on your Business Profile page, these endpoints return 403 Forbidden with error_code: PROFILE_INCOMPLETE.

You never need an ID we generated. Every invoice endpoint identifies a customer by the customer block's no — your own customer number — which we match against your existing customers and create from if it's new. Items work the same way: send a line freeform (item_name + item_type + tax_category + category), or reference an existing catalog item by lines.*.item_id if you manage your catalog in the web dashboard. There's no endpoint here to list or manage the customer/item catalog itself.

Responses follow the shared envelope described in Errors & Response Format.

Quick start

Step 1 — create your first invoice

bash

curl -X POST https://invoice-direct.gemspaysolution.com/api/v1/tax-payers/invoices \
  -H "x-api-key: tpk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_no": "INV-001",
    "invoice_category": "B2B",
    "invoice_type": "Standard",
    "invoice_date": "2025-10-24",
    "due_date": "2025-11-07",
    "currency": "NGN",
    "customer": {
      "no": "CUST-001",
      "name": "Acme Corp Ltd",
      "tin": "1234567890",
      "email": "finance@acme.ng",
      "address_street_name": "5 Marina Street",
      "address_city": "Lagos",
      "address_state": "Lagos",
      "address_postal_code": "100001",
      "address_country": "Nigeria"
    },
    "invoice_lines": [
      {
        "item_name": "Software Development",
        "item_no": "SVC-001",
        "item_type": "SERVICE",
        "unit_price": 500000,
        "quantity": 1,
        "tax_category": "STANDARD_VAT",
        "service_category": "SOFTWARE_DEVELOPMENT"
      }
    ]
  }'

Step 2 — retrieve it

bash

curl https://invoice-direct.gemspaysolution.com/api/v1/tax-payers/invoices/get-by-unique-no \
  -H "x-api-key: tpk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"unique_no": "INV-001", "unique_no_type": "INTERNAL_INVOICE_NO"}'

Step 3 — approve, then mark paid

bash

curl -X PATCH https://invoice-direct.gemspaysolution.com/api/v1/tax-payers/invoices/update-status \
  -H "x-api-key: tpk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"unique_no": "INV-001", "unique_no_type": "INTERNAL_INVOICE_NO", "status": "approved", "remark": "Reviewed and approved"}'

curl -X PATCH https://invoice-direct.gemspaysolution.com/api/v1/tax-payers/invoices/update-payment-status \
  -H "x-api-key: tpk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"unique_no": "INV-001", "unique_no_type": "INTERNAL_INVOICE_NO", "status": "paid", "remark": "Payment confirmed"}'

Taxpayer API

Quick start

Continue As