Update Invoice Payment Status
POST
{{baseUrl}}/{{stage}}/external/businesses/{{businessId}}/invoices/update-payment/{{invoiceIrn}}
POST {{baseUrl}}/{{stage}}/external/businesses/{{businessId}}/invoices/update-payment/{{invoiceIrn}}?invoiceStatus={{status}}Request
Headers
| Header | Value | Required |
|---|---|---|
Content-Type | application/json or */* | Yes |
Accept | application/json or */* | Yes |
X-Business-Key | businessKey | Yes |
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
businessId | string (UUID) | Yes | Your business FIRS ID |
invoiceIrn | string | Yes | Invoice Reference Number |
Query Parameters
| Parameter | Type | Required | Allowed Values |
|---|---|---|---|
invoiceStatus | string | Yes | PENDING, PAID, REJECTED |
Response
Success (200)
{
"responseCode": "00",
"responseMessage": "Success"
}| Field | Description |
|---|---|
responseCode | "00" = success |
responseMessage | Status update confirmation |
Errors
{
"responseCode": "404",
"responseMessage": "Invoice not found with IRN: INV999-INVALID"
}invoiceIrn exists and belongs to businessId{
"responseCode": "400",
"responseMessage": "Invalid status value"
}{
"responseCode": "403",
"responseMessage": "Unauthorized: Business ID doesn't match invoice owner"
}businessId matches invoice owner{
"responseCode": "422",
"responseMessage": "Status change not permitted"
}Example Requests
Status Transitions
PENDING → PAID (payment received)
PENDING → REJECTED (payment declined)
REJECTED → PENDING (retry payment)Common Issues
→ Verify IRN format and business ownership
→ Cannot change PAID invoices back to PENDING without authorization
→ Check invoice is not cancelled or in final state
Best Practices
✅ Verify first - Check invoice exists before updating
✅ Handle errors - Implement proper error handling for failed updates
✅ Reconcile regularly - Match payment status with actual payment records
Security Notes
⚠️ Maintain audit logs of who updated status and when
⚠️ Implement rate limiting to prevent abuse
Request
Query Params
Header Params
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --globoff --request POST '{{baseUrl}}/{{stage}}/external/businesses/{{businessId}}/invoices/update-payment/{{invoiceIrn}}?invoiceStatus=PAID&invoiceStatus={{status}}' \
--header 'X-Business-Key: BK-26EDE24BAC50475FAACC5EA6339F0863-DEV-B2Z6QCEHI3X9' \
--header 'Accept: */*' \
--header 'Content-Type: application/json'Response Response Example
{}Modified at 2026-08-21 08:50:04