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

​
Path Parameters

​
id
string
required
Collection ID

​
Request Body

​
status
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

​
status
string
Response status (“success”)
​
message
string
Success message
​
data
object
Full collection object with updated status
​
data.status
string
Updated status
​
data.completedAt
string
ISO 8601 timestamp (set when status is “completed”)
​
data.events
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