Update Collection Status

Updates the status of a collection. This is typically called when your payment provider sends webhook notifications about payment status changes.

Path Parameters

string

required

Collection ID

Request Body

string

required

New status. Valid values:

pending: Payment is pending
completed: Payment was successful
expired: Collection has expired
overdue: Payment is overdue
cancelled: Collection was cancelled

Status Transition Rules

Once a collection is completed, expired, cancelled, or overdue, it cannot be changed to another status
You cannot set a collection to pending if it’s already pending
When status changes to a terminal state (completed, expired, cancelled, overdue), any active follow-ups are automatically stopped

Example Request

{
  "status": "completed"
}

Response

string

Response status (“success”)

string

Success message

object

Full collection object with updated status

string

Updated status

string

ISO 8601 timestamp (set when status is “completed”)

array

Updated events array including new status change event

Example Response

{
  "status": "success",
  "message": "Collection status updated successfully",
  "data": {
    "id": "pay_9fmz6170pzaih14pmyl0a49o1l",
    "type": "integrated",
    "contact": {
      "id": "contact_gj7iyx04gs7hticrite6m6qdhc",
      "firstName": "Amina",
      "lastName": "Lawal",
      "phone": "+2348012345678",
      "email": "[email protected]"
    },
    "reference": "PSK_txn_8a7f34",
    "amount": {
      "value": 45000,
      "currency": "NGN"
    },
    "status": "completed",
    "expiresIn": 1440,
    "payable": {
      "enabled": true,
      "methods": ["payment_link", "virtual_account"],
      "options": []
    },
    "followUp": {
      "enabled": true,
      "startAfter": 20,
      "cadence": "every_10m",
      "channels": ["whatsapp", "sms"],
      "tone": "gentle"
    },
    "metadata": [
      {
        "name": "Standard Membership",
        "amount": {
          "value": 15000,
          "currency": "NGN"
        },
        "description": "January plan renewal",
        "quantity": 1
      }
    ],
    "events": [
      {
        "id": "evt_xxx",
        "type": "collection.created",
        "timestamp": "2025-11-12T17:46:07.000Z"
      },
      {
        "id": "evt_yyy",
        "type": "collection.successful",
        "timestamp": "2025-11-12T18:30:00.000Z"
      },
      {
        "id": "evt_zzz",
        "type": "followup.stopped",
        "timestamp": "2025-11-12T18:30:00.000Z"
      }
    ],
    "createdAt": "2025-11-12T17:46:07.000Z",
    "updatedAt": "2025-11-12T18:30:00.000Z",
    "completedAt": "2025-11-12T18:30:00.000Z"
  }
}

Notes

Status updates automatically create events in the collection’s event history
When status changes to a terminal state, follow-up is automatically stopped
The followup.stopped event is added when follow-up is stopped

API Documentation

Collections

Providers

Update Collection Status

Path Parameters

Request Body

Status Transition Rules

Example Request

Response

Example Response

Notes

​Path Parameters

​Request Body

​Status Transition Rules

​Example Request

​Response

​Example Response

​Notes

Path Parameters

Request Body

Status Transition Rules

Example Request

Response

Example Response

Notes