Update Invoice Payment Status

Update the payment status of an existing invoice to reflect payment completion or status changes.

Quick Reference

Method Endpoint Authentication Required
POST https://api-dev.nairainvoice.com/dev/external/businesses/:businessId/invoices/update-payment/:invoiceIrn ✅ Yes

Request Structure

Path Parameters

Parameter Type Required Description Example
businessId string ✅ The unique identifier of the business 26ede24b-ac50-475f-aacc-5ea6339f0863
invoiceIrn string ✅ The Invoice Reference Number of the invoice to update INV237-1070ECE8-20250826

Query Parameters

Parameter Type Required Description Allowed Values
invoiceStatus string ✅ The new payment status for the invoice PENDING, PAID, REJECTED

📋 Payment Status Options

Status Description Use Case
PENDING Invoice payment is pending Initial status when invoice is created and awaiting payment
PAID Invoice has been fully paid Mark invoice as completed when full payment received
REJECTED Invoice payment has been rejected Mark invoice when payment is declined or rejected

📤 Response Format

Success Response (200)

Copy to Clipboard

Response Fields

Field Type Description Possible Values
responseCode string Result code of the update operation "00" (success), error codes for failures
responseMessage string Descriptive message about the operation "Success", error descriptions

📝 Example Usage

Mark Invoice as Pending

Copy to Clipboard

Mark Invoice as Paid

Copy to Clipboard

Mark Invoice as Rejected

Copy to Clipboard

✅ Validation Rules

Required Parameters

  • businessId must be a valid business identifier
  • invoiceIrn must be a valid, existing Invoice Reference Number
  • invoiceStatus must be one of the allowed values

Business Logic Validation

  • Invoice must exist and belong to the specified business
  • Invoice must be in a state that allows payment status updates
  • Status transitions must be logical (e.g., cannot mark a paid invoice as unpaid without proper authorization)

⚠️ Error Responses

Common Error Scenarios

Error Code Message Description Solution
404 Invoice not found The specified invoice IRN doesn’t exist Verify the invoice IRN is correct
400 Invalid status The provided status is not allowed Use one of the valid status values
403 Unauthorized Business ID doesn’t match invoice owner Ensure correct business ID is used
422 Invalid transition Status change not permitted Check current invoice status and business rules

Example Error Response

Copy to Clipboard

🔄 Status Transition Flow

Copy to Clipboard

Allowed Transitions

  • PENDING → PAID, REJECTED
  • PAID → PENDING (with special permissions)
  • REJECTED → PENDING (for reprocessing)

💡 Best Practices

Implementation Guidelines

  • Verify invoice existence before attempting status updates
  • Log payment updates for audit trail purposes
  • Handle errors gracefully with appropriate user feedback
  • Use transaction logs to track payment history

Integration Tips

  • Batch updates: For multiple invoices, consider implementing batch processing
  • Webhook notifications: Set up webhooks to notify other systems of payment updates
  • Reconciliation: Regularly reconcile payment statuses with actual payment records

Security Considerations

  • Validate permissions before allowing payment status changes
  • Audit trail: Maintain logs of who updated payment status and when
  • Rate limiting: Implement rate limiting to prevent abuse

🔗 Related Endpoints

Invoice Management

Copy to Clipboard

Payment Tracking

Copy to Clipboard

📊 Use Cases

Common Scenarios

1. Payment Received

Copy to Clipboard

2. Payment Pending

Copy to Clipboard

3. Payment Rejected

Copy to Clipboard

4. Payment Retry

Copy to Clipboard

This endpoint is essential for maintaining accurate payment tracking within the invoice management system, ensuring real-time visibility into payment status and enabling effective accounts receivable management.

Request

📘 Path Parameters

Parameter Type Required Example
businessId string ✅ required 26ede24b-ac50-475f-aacc-5ea6339f0863
invoiceIrn string ✅ required INGH8999888-FCD1AC50-20251012

📘 Query Parameters

Parameter Type Required Example
invoiceStatus string ✅ required PAID

📋 Header Parameters

Header Type Required Description Example
X-Business-Key string ✅ required (Required) X-Business-Key BK-26EDE24BAC50475FAACC5EA6339F0863-DEV-B2Z6QCEHI3X9
Content-Type string ✅ required application/json
Accept string ✅ required */*

Responses

  • 200 Success