Invoice Reversal

Reverse an existing invoice by providing its Invoice Reference Number (IRN). This operation creates a credit note on that invoice.

Quick Reference

Method	Endpoint	Content-Type
`POST`	`{{baseUrl}}/{{stage}}/external/businesses/{{businessId}}/invoices/reversal`	`application/json`

Request Structure

Path Parameters

Parameter	Type	Required	Description
`businessId`	string	✅	The unique identifier of the business

Headers

Header	Value	Required
`Content-Type`	`application/json` or `/`	Yes
`Accept`	`application/json` or `/`	Yes
`X-Business-Key`	`businessKey`	Yes

📋 Request Body

Field	Type	Required	Description	Validation
`irn`	string	✅	Invoice Reference Number	Must be a valid IRN format

Example: INV236-1070ECE8-20250826

📤 Response Format

Success Response (200)

{
  "responseCode": "00",
  "responseMessage": "Success",
  "data": {
    "requestType": null,
    "invoiceId": 134,
    "invoiceBusinessId": "26ede24b-ac50-475f-aacc-5ea6339f0863",
    "invoiceEntityId": "107",
    "invoiceIssueDate": "2025-08-26",
    "invoiceIrn": "INV236-1070ECE8-20250826",
    "invoiceDueDate": "2025-08-26",
    "invoiceIssueTime": "12:57:15",
    "invoiceTypeCode": "389",
    "invoicePaymentStatus": "PAID",
    "invoiceNote": "August Electricity Bill - Mr Ridwan",
    "invoiceTaxPointDate": "2025-08-26",
    "invoiceDocumentCurrencyCode": "NGN",
    "invoiceTaxCurrencyCode": "NGN",
    "invoiceStatus": "PENDING",
    "invoiceCreatedAt": "2025-08-27T09:25:35.694193",
    "invoiceUpdatedAt": "2025-08-27T08:33:50.756293",
    
    "invoiceCustomerPartyTin": "68721523-8104",
    "invoiceCustomerPartyEmail": "supplier_business@email.com",
    "invoiceCustomerPartyTelephone": "+23480254099000",
    "invoiceCustomerPartyBusinessDescription": "this entity is into sales of Cement and building materials",
    "invoiceCustomerPartyName": "Dangote Group",
    "invoiceCustomerCityName": "Gwarikpa",
    "invoiceCustomerPostalZone": "023401",
    "invoiceCustomerCountry": "NG",
    "invoiceCustomerStreetName": "32, owonikoko street",
    "invoiceCustomerLga": "Aba",
    "invoiceCustomerState": "Abia",
    
    "invoiceSupplierPartyId": "b4009129-ece8-45fc-9584-976fcbe35f8d",
    "invoiceSupplierPartyTin": "68721523-8104",
    "invoiceSupplierPartyEmail": "redtech@gmail.com",
    "invoiceSupplierPartyTelephone": "+234447784433",
    "invoiceSupplierPartyBusinessDescription": "AEDC Electricity Supply",
    "invoiceSupplierPartyName": "alias-sit-fuga-ex",
    "invoiceSupplierLga": "Aba",
    "invoiceSupplierState": "Abia",
    "invoiceSupplierCityName": "Aba",
    "invoiceSupplierPostalZone": "101245",
    "invoiceSupplierCountry": "NG",
    "invoiceSupplierStreetName": "vi",
    
    "invoiceLineExtensionAmount": 30030,
    "invoiceTaxExclusiveAmount": 30030,
    "invoiceTaxInclusiveAmount": 30255.22,
    "invoicePayableAmount": 30255.22,
    
    "invoiceLine": [
      {
        "invoiceLineInvoiceId": 134,
        "invoiceLineProductCategory": "Electrical energy",
        "invoiceLineDiscountRate": 0.1,
        "invoiceLineDiscountAmount": 30,
        "invoiceLineFeeRate": 0.2,
        "invoiceLineFeeAmount": 60,
        "invoiceLineInvoicedQuantity": 200,
        "invoiceLineExtensionAmount": 30030,
        "invoiceLineHsnCode": "2716.00",
        "invoiceLineItemDescription": "Electricity Units",
        "invoiceLineItemSellersItemIdentification": "Electricity Units",
        "invoiceLineItemName": "Electricity Supply",
        "invoiceLinePriceBaseQuantity": 1,
        "invoiceLinePriceUnit": "NGN PER 1",
        "invoiceLinePriceAmount": 150
      }
    ],
    
    "invoiceTaxTotal": [
      {
        "invoiceTaxTotalInvoiceId": 134,
        "invoiceTaxTotalAmount": null,
        "invoiceTaxTotalSubTotal": [
          {
            "taxSubTotalTaxableAmount": 30030,
            "taxSubTotalTaxAmount": 225.22,
            "taxSubTotalCategoryId": "STANDARD_VAT",
            "taxSubTotalCategoryPercent": 0.75
          }
        ]
      }
    ]
  }
}

Response Fields

Top-Level Response

Field	Type	Description
`responseCode`	string	Response status code (`"00"` = success)
`responseMessage`	string	Human-readable response message
`data`	object	Invoice data object

Invoice Core Details

Field	Type	Description
`invoiceId`	number	Unique invoice identifier
`invoiceBusinessId`	string	Business ID associated with invoice
`invoiceEntityId`	string	Entity ID for the invoice
`invoiceIrn`	string	Invoice Reference Number
`invoiceIssueDate`	string	Date invoice was issued (YYYY-MM-DD)
`invoiceDueDate`	string	Payment due date (YYYY-MM-DD)
`invoiceIssueTime`	string	Time invoice was issued (HH:MM:SS)
`invoiceTypeCode`	string	Invoice type code
`invoicePaymentStatus`	string	Payment status (e.g., "PAID", "UNPAID")
`invoiceStatus`	string	Current invoice status (e.g., "PENDING", "REVERSED")
`invoiceNote`	string	Additional notes or description
`invoiceDocumentCurrencyCode`	string	Invoice currency code
`invoiceTaxCurrencyCode`	string	Tax currency code
`invoiceCreatedAt`	string	Timestamp when invoice was created
`invoiceUpdatedAt`	string	Timestamp when invoice was last updated

Customer Information

Field	Type	Description
`invoiceCustomerPartyTin`	string	Customer Tax Identification Number
`invoiceCustomerPartyEmail`	string	Customer email address
`invoiceCustomerPartyTelephone`	string	Customer phone number
`invoiceCustomerPartyName`	string	Customer name
`invoiceCustomerPartyBusinessDescription`	string	Customer business description
`invoiceCustomerCityName`	string	Customer city
`invoiceCustomerPostalZone`	string	Customer postal code
`invoiceCustomerCountry`	string	Customer country code
`invoiceCustomerStreetName`	string	Customer street address
`invoiceCustomerLga`	string	Customer Local Government Area
`invoiceCustomerState`	string	Customer state

Supplier Information

Field	Type	Description
`invoiceSupplierPartyId`	string	Supplier party ID
`invoiceSupplierPartyTin`	string	Supplier Tax Identification Number
`invoiceSupplierPartyEmail`	string	Supplier email address
`invoiceSupplierPartyTelephone`	string	Supplier phone number
`invoiceSupplierPartyName`	string	Supplier name
`invoiceSupplierPartyBusinessDescription`	string	Supplier business description
`invoiceSupplierCityName`	string	Supplier city
`invoiceSupplierPostalZone`	string	Supplier postal code
`invoiceSupplierCountry`	string	Supplier country code
`invoiceSupplierStreetName`	string	Supplier street address
`invoiceSupplierLga`	string	Supplier Local Government Area
`invoiceSupplierState`	string	Supplier state

Financial Summary

Field	Type	Description
`invoiceLineExtensionAmount`	number	Line extension total amount
`invoiceTaxExclusiveAmount`	number	Total amount excluding tax
`invoiceTaxInclusiveAmount`	number	Total amount including tax
`invoicePayableAmount`	number	Total amount payable

Line Items

Field	Type	Description
`invoiceLine`	array	Array of invoice line items
`invoiceLineInvoiceId`	number	Associated invoice ID
`invoiceLineProductCategory`	string	Product category
`invoiceLineDiscountRate`	number	Discount rate applied
`invoiceLineDiscountAmount`	number	Discount amount
`invoiceLineFeeRate`	number	Fee rate applied
`invoiceLineFeeAmount`	number	Fee amount
`invoiceLineInvoicedQuantity`	number	Quantity invoiced
`invoiceLineExtensionAmount`	number	Line item total amount
`invoiceLineHsnCode`	string	HSN classification code
`invoiceLineItemDescription`	string	Item description
`invoiceLineItemName`	string	Item name
`invoiceLinePriceBaseQuantity`	number	Base quantity for pricing
`invoiceLinePriceUnit`	string	Price unit description
`invoiceLinePriceAmount`	number	Price per unit

Tax Information

Field	Type	Description
`invoiceTaxTotal`	array	Array of tax totals
`invoiceTaxTotalInvoiceId`	number	Associated invoice ID
`invoiceTaxTotalAmount`	number	Total tax amount
`invoiceTaxTotalSubTotal`	array	Array of tax subtotals by category
`taxSubTotalTaxableAmount`	number	Taxable amount
`taxSubTotalTaxAmount`	number	Tax amount for this category
`taxSubTotalCategoryId`	string	Tax category identifier
`taxSubTotalCategoryPercent`	number	Tax percentage rate

📝 Example Request

cURL Example

JSON Request Body

{
  "irn": "INV123456-10EC108B-25670494"
}

✅ Validation Rules

Request Validation

businessId: Must be a valid UUID format in the URL path

X-Business-Key: Required authentication header, must be valid

irn: Required field, must match an existing invoice IRN

Business Logic Validation

The specified invoice must exist in the system

The invoice must belong to the specified business

The invoice must be in a reversible state

User must have appropriate permissions to reverse invoices

⚠️ Error Responses

Common Error Codes

Status Code	Response Code	Description
400	-	Bad Request - Invalid IRN format or missing required fields
401	-	Unauthorized - Invalid or missing X-Business-Key
404	-	Not Found - Invoice with specified IRN does not exist
403	-	Forbidden - Insufficient permissions to reverse invoice
409	-	Conflict - Invoice cannot be reversed (already reversed or in invalid state)

Error Response Format

{
  "responseCode": "ERROR_CODE",
  "responseMessage": "Error description",
  "data": null
}

💡 Use Cases

When to Use This Endpoint

Accounting Corrections: Reverse an invoice that was issued incorrectly

Transaction Cancellations: Cancel a transaction that needs to be voided

Credit Note Generation: Create a reversal for issuing credits to customers

Compliance Requirements: Maintain audit trails for reversed transactions

Important Considerations

A reversal will trigger the creation of a credit note or adjustment entry

Reversed invoices usually cannot be un-reversed; a new invoice must be created instead

📊 Workflow Example

1. Create Invoice (POST /invoices)
   ↓
2. Invoice Issued (Status: TRANSMITTING/TRANSMITTED)
   ↓
3. Need to Reverse (Error/Cancellation)
   ↓
4. Call Reversal Endpoint (POST /invoices/reversal)
   ↓
5. Invoice Reversed (creates a credit note on that invoice)
   ↓
6. Create New Corrected Invoice (if needed)

Invoice Reversal

Quick Reference#

Request Structure#

Path Parameters#

Headers#

📋 Request Body#

📤 Response Format#

Success Response (200)#

Response Fields#

Top-Level Response#

Invoice Core Details#

Customer Information#

Supplier Information#

Financial Summary#

Line Items#

Tax Information#

📝 Example Request#

cURL Example#

JSON Request Body#

✅ Validation Rules#

Request Validation#

Business Logic Validation#

⚠️ Error Responses#

Common Error Codes#

Error Response Format#

💡 Use Cases#

When to Use This Endpoint#

Important Considerations#

📊 Workflow Example#

Request

Responses