Webhook Event Catalog

This page lists the webhook events that MeSomb can send to your application.

Each event uses the same webhook envelope and includes a snapshot of the affected resource in data.object.

Event categories

MeSomb webhook events are grouped by business domain:

CategoryDescription
Payment transaction eventsEvents related to standard payment collection transactions.
Checkout session eventsEvents related to hosted checkout sessions.
Secure payment eventsEvents related to escrow-style or secure payment transactions.
Dispute eventsEvents related to disputes and evidence.
Refund eventsEvents related to refunds.
Payout eventsEvents related to transfers or payouts to merchants.

Payment transaction events

Payment transaction events are sent when the status of a standard payment transaction changes.

Event Type: payment.transaction.success

Sent when a payment transaction has been successfully completed.

Typical use cases:

  • mark an order as paid;
  • unlock access to a service;
  • trigger fulfillment;
  • issue a receipt;
  • update accounting or reconciliation records.

Event Type: payment.transaction.failed

Sent when a payment transaction has failed.

Typical use cases:

  • mark an order payment attempt as failed;
  • allow the customer to retry payment;
  • notify the merchant that payment was not completed.

Object schema

This is the schema of the data.object field in the webhook event payload:

  • Name
    amount
    Type
    float
    Required
    required
    Description

    The amount of the transaction

  • Name
    country
    Type
    enum
    Required
    required
    Description
  • Name
    currency
    Type
    string
    Required
    required
    Description

    The currency of the transaction

  • Name
    fees
    Type
    double
    Required
    required
    Description

    The fees of the transaction

  • Name
    service
    Type
    enum
    Required
    required
    Description

    Payment service of the transaction

    • MTN - MTN
    • ORANGE - ORANGE
    • AIRTEL - AIRTEL
  • Name
    status
    Type
    enum
    Required
    required
    Description

    The status of the transaction

    • SUCCESS - SUCCESS
    • FAILED - FAILED
    • PENDING - PENDING
    • REFUNDED - REFUNDED
  • Name
    trxamount
    Type
    float
    Required
    required
    Description

    The amount of the transaction after fees

  • Name
    ts
    Type
    date-time
    Required
    required
    Description

    The date and time of the transaction

  • Name
    type
    Type
    enum
    Required
    required
    Description
  • Name
    b_party
    Type
    string | nullable
    Description

    The receiver or sender of the transaction

  • Name
    customer
    Type
    object | nullable
    Description

    Details on the customer performing the transaction

  • Name
    customer > address
    Parent
    in customer
    Type
    string
    Required
    required
    Description

    The address of the customer

  • Name
    customer > id
    Parent
    in customer
    Type
    integer
    Required
    required
    Description
  • Name
    customer > country
    Parent
    in customer
    Type
    string | nullable
    Description

    Living country of the customer

  • Name
    customer > email
    Parent
    in customer
    Type
    email | nullable
    Description

    Contact email of the customer

  • Name
    customer > first_name
    Parent
    in customer
    Type
    string | nullable
    Description

    First name of the customer

  • Name
    customer > last_name
    Parent
    in customer
    Type
    string | nullable
    Description

    Last name of the customer

  • Name
    customer > phone
    Parent
    in customer
    Type
    string | nullable
    Description

    Contact phone of the customer

  • Name
    customer > region
    Parent
    in customer
    Type
    string | nullable
    Description

    Living region of the customer

  • Name
    customer > town
    Parent
    in customer
    Type
    string | nullable
    Description

    Living town of the customer

  • Name
    direction
    Type
    enum
    Description
  • Name
    fin_trx_id
    Type
    string | nullable
    Description

    The operator transaction ID

  • Name
    location
    Type
    object | nullable
    Description

    Location for where the transaction was done.

  • Name
    location > country
    Parent
    in location
    Type
    string | nullable
    Description

    Country from where the transaction was performed

  • Name
    location > region
    Parent
    in location
    Type
    string | nullable
    Description

    Region from where the transaction was performed

  • Name
    location > town
    Parent
    in location
    Type
    string
    Description

    Town from where the transaction was performed

  • Name
    message
    Type
    string | nullable
    Description

    A customer to send to the customer

  • Name
    name
    Type
    string | nullable
    Description

    A nice name for the transaction (reference param during the request)

  • Name
    pk
    Type
    uuid
    Description
  • Name
    reference
    Type
    string
    Description

    The reference of the transaction for your system, trxId pass during the request

Checkout session events

Checkout session events are sent when a hosted checkout session changes state.

A checkout session represents the customer-facing payment flow. It may create or reference one or more payment transactions.

Event Type: checkout.session.completed

Sent when a checkout session is successfully completed.

Typical use cases:

  • mark the customer checkout flow as completed;
  • update the order as paid if payment_status is paid;
  • link the checkout session to the payment transaction.

Event Type: checkout.session.expired

Sent when a checkout session expires before successful payment.

Typical use cases:

  • mark checkout as expired;
  • release reserved stock;
  • allow the customer to create a new checkout session.

Event Type: checkout.session.canceled

Sent when a checkout session is cancelled.

Typical use cases:

  • mark checkout as cancelled;
  • redirect customer to retry flow;
  • keep the order unpaid.

Event Type: checkout.session.created

Sent when a checkout session is created.

Typical use cases:

  • store the checkout session ID;
  • redirect the customer to the checkout URL;
  • show checkout as pending.

Object schema

This is the schema of the data.object field in the webhook event payload:

  • Name
    amount
    Type
    double
    Required
    required
    Description

    Amount in minor units (e.g., cents)

  • Name
    attempt_count
    Type
    integer
    Required
    required
    Description
  • Name
    cancel_url
    Type
    uri
    Required
    required
    Description
  • Name
    created_at
    Type
    date-time
    Required
    required
    Description
  • Name
    expires_at
    Type
    date-time
    Required
    required
    Description
  • Name
    failure_code
    Type
    string | nullable
    Required
    required
    Description
  • Name
    failure_message
    Type
    string | nullable
    Required
    required
    Description
  • Name
    id
    Type
    string
    Required
    required
    Description
  • Name
    object
    Type
    string
    Required
    required
    Description
  • Name
    status
    Type
    enum
    Required
    required
    Description
  • Name
    success_url
    Type
    uri
    Required
    required
    Description
  • Name
    updated_at
    Type
    date-time
    Required
    required
    Description
  • Name
    url
    Type
    string
    Required
    required
    Description
  • Name
    allowed_payment_methods
    Type
    undefined
    Description

    List of allowed payment methods

  • Name
    amount_total
    Type
    double | nullable
    Description

    Amount in minor units (e.g., cents)

  • Name
    branding_settings
    Type
    object | nullable
    Description

    Branding settings for this session

  • Name
    branding_settings > background_color
    Parent
    in branding_settings
    Type
    string
    Description

    A hex color value starting with # representing the background color

  • Name
    branding_settings > border_style
    Parent
    in branding_settings
    Type
    enum
    Description

    The border style for the widget.

    • pill - pill
    • rectangular - rectangular
    • rounded - rounded
  • Name
    branding_settings > button_color
    Parent
    in branding_settings
    Type
    string
    Description

    A hex color value starting with # representing the button color for the pay widget

  • Name
    branding_settings > display_name
    Parent
    in branding_settings
    Type
    string
    Description

    A string to override the business name shown on the pay widget. This only shows at the top of the Checkout page, and your business name still appears in terms, receipts, and other places.

  • Name
    branding_settings > font_family
    Parent
    in branding_settings
    Type
    enum
    Description

    The font family for the Checkout Session corresponding to one of the [supported font families]

    • be_vietnam_pro - be_vietnam_pro
    • bitter - bitter
    • chakra_petch - chakra_petch
    • default - default
    • hahmlet - hahmlet
    • inconsolata - inconsolata
    • inter - inter
    • lato - lato
    • lora - lora
    • m_plus_1_code - m_plus_1_code
    • montserrat - montserrat
    • noto_sans - noto_sans
    • noto_sans_jp - noto_sans_jp
    • noto_serif - noto_serif
    • nunito - nunito
    • open_sans - open_sans
    • pridi - pridi
    • pt_sans - pt_sans
    • pt_serif - pt_serif
    • raleway - raleway
    • roboto - roboto
    • roboto_slab - roboto_slab
    • source_sans_pro - source_sans_pro
    • titillium_web - titillium_web
    • ubuntu_mono - ubuntu_mono
    • zen_maru_gothic - zen_maru_gothic
  • Name
    client_reference_id
    Type
    string | nullable
    Description

    A unique string to reference the Checkout Session. This can be a customer ID, a cart ID, or similar, and can be used to reconcile the session with your internal systems.

  • Name
    currency
    Type
    string
    Description
  • Name
    customer
    Type
    undefined
    Description
  • Name
    description
    Type
    string | nullable
    Description
  • Name
    escrow_mode
    Type
    enum
    Description
  • Name
    line_items
    Type
    array
    Description

    Optional product line items to display during checkout

  • Name
    line_items > adjustable
    Parent
    in line_items
    Type
    boolean
    Description

    If set to true, the line item will be adjustable.

  • Name
    line_items > currency
    Parent
    in line_items
    Type
    string
    Default
    Default: XAF
    Description

    Currency of the transaction: can be local country local currency or foreign currency

  • Name
    line_items > limit_max
    Parent
    in line_items
    Type
    integer
    Description

    Maximum quantity allowed for this line item.

  • Name
    line_items > limit_min
    Parent
    in line_items
    Type
    integer
    Description

    Minimum quantity allowed for this line item.

  • Name
    line_items > product
    Parent
    in line_items
    Type
    string
    Description

    ID of an existing Product record to add to this session

  • Name
    line_items > product_data
    Parent
    in line_items
    Type
    object | nullable
    Description

    Data used to generate a new [Product]

  • Name
    line_items > product_data > name
    Parent
    in line_items.product_data
    Type
    string
    Required
    required
    Description

    The name of the product being purchased.

  • Name
    line_items > product_data > description
    Parent
    in line_items.product_data
    Type
    string | nullable
    Description

    A description of this product.

  • Name
    line_items > product_data > images
    Parent
    in line_items.product_data
    Type
    array
    Description

    A list of up to 8 URLs of images for this product.

  • Name
    line_items > product_data > metadata
    Parent
    in line_items.product_data
    Type
    object
    Description

    Metadata associated with this product.

  • Name
    line_items > product_data > unit_label
    Parent
    in line_items.product_data
    Type
    string | nullable
    Description

    A label that represents units of this product.

  • Name
    line_items > quantity
    Parent
    in line_items
    Type
    integer
    Default
    Default: 1
    Description
  • Name
    line_items > unit_amount
    Parent
    in line_items
    Type
    double
    Description
  • Name
    metadata
    Type
    undefined
    Description

Secure payment events

Secure payment events are used for escrow-style payment flows where funds may be held until delivery confirmation, release, dispute resolution, or refund.

Event Type: securepay.transaction.created

Sent when a secure payment transaction is created.

Typical use cases:

  • create a secure payment record in your system;
  • show the buyer and seller that secure payment has started.

Event Type: securepay.transaction.cancelled

Sent when a secure payment is cancelled before completion.

Typical use cases:

  • close pending secure payment flow;
  • release internal reservations;
  • prevent further delivery or settlement steps.

Event Type: securepay.transaction.expired

Sent when a checkout session expires before successful payment.

Typical use cases:

  • mark checkout as expired;
  • release reserved stock;
  • allow the customer to create a new checkout session.

Event Type: securepay.transaction.funded

Sent when the buyer has paid and the secure payment is funded.

Typical use cases:

  • notify the seller to prepare or deliver the item;
  • mark the order as funded but not yet released;
  • prevent premature settlement to the seller.

Event Type: securepay.transaction.awaiting_release

Sent when a secure pay transaction is awaiting release.

Typical use cases:

  • notify the seller to prepare or deliver the item;
  • mark the order as funded but not yet released;
  • prevent premature settlement to the seller.

Event Type: securepay.transaction.released

Sent when secure payment funds are released to the seller.

Typical use cases:

  • mark the order as completed;
  • update seller settlement balance;
  • notify seller that funds have been released;
  • close the secure payment lifecycle.

Event Type: securepay.transaction.refunded

Sent when a secure payment is refunded to the buyer.

Typical use cases:

  • mark secure payment as refunded;
  • close related dispute if applicable;
  • update buyer and seller records;
  • prevent fulfillment or settlement.

Event Type: securepay.transaction.disputed

Sent when a dispute is created.

Typical use cases:

  • open a support case;
  • notify operations team;
  • pause release of funds;
  • request evidence from parties.

Event Type: securepay.transaction.fulfillment_updated

Sent when a secure pay transaction fulfillment is updated by the seller.

Typical use cases:

  • update fulfillment status in your system;
  • track shipping or delivery progress;
  • trigger notifications or follow-up actions based on fulfillment updates.
  • update secure payment status.

Object schema

This is the schema of the data.object field in the webhook event payload:

  • Name
    amount
    Type
    float
    Required
    required
    Description

    The amount of the transaction

  • Name
    country
    Type
    string
    Required
    required
    Description
    • CM - CM
    • NE - NE
  • Name
    currency
    Type
    string
    Required
    required
    Description

    The currency of the transaction

  • Name
    fees
    Type
    double
    Required
    required
    Description

    The fees of the transaction

  • Name
    service
    Type
    string
    Required
    required
    Description

    Payment service of the transaction

    • MTN - MTN
    • ORANGE - ORANGE
    • AIRTEL - AIRTEL
  • Name
    status
    Type
    string
    Required
    required
    Description

    The status of the transaction

    • SUCCESS - SUCCESS
    • FAILED - FAILED
    • PENDING - PENDING
    • REFUNDED - REFUNDED
  • Name
    trxamount
    Type
    float
    Required
    required
    Description

    The amount of the transaction after fees

  • Name
    ts
    Type
    date-time
    Required
    required
    Description

    The date and time of the transaction

  • Name
    type
    Type
    string
    Required
    required
    Description
    • COLLECT - Collect
    • REFILL - Refill
    • PAYMENT - Payment
    • DEPOSIT - Deposit
  • Name
    b_party
    Type
    string | nullable
    Description

    The receiver or sender of the transaction

  • Name
    customer
    Type
    object | nullable
    Description

    Details on the customer performing the transaction

  • Name
    customer > address
    Parent
    in customer
    Type
    string
    Required
    required
    Description

    The address of the customer

  • Name
    customer > id
    Parent
    in customer
    Type
    integer
    Required
    required
    Description
  • Name
    customer > country
    Parent
    in customer
    Type
    string | nullable
    Description

    Living country of the customer

  • Name
    customer > email
    Parent
    in customer
    Type
    email | nullable
    Description

    Contact email of the customer

  • Name
    customer > first_name
    Parent
    in customer
    Type
    string | nullable
    Description

    First name of the customer

  • Name
    customer > last_name
    Parent
    in customer
    Type
    string | nullable
    Description

    Last name of the customer

  • Name
    customer > phone
    Parent
    in customer
    Type
    string | nullable
    Description

    Contact phone of the customer

  • Name
    customer > region
    Parent
    in customer
    Type
    string | nullable
    Description

    Living region of the customer

  • Name
    customer > town
    Parent
    in customer
    Type
    string | nullable
    Description

    Living town of the customer

  • Name
    direction
    Type
    integer
    Description
    • -1 - Debit
    • 1 - Credit
  • Name
    fin_trx_id
    Type
    string | nullable
    Description

    The operator transaction ID

  • Name
    location
    Type
    object | nullable
    Description

    Location for where the transaction was done.

  • Name
    location > country
    Parent
    in location
    Type
    string | nullable
    Description

    Country from where the transaction was performed

  • Name
    location > region
    Parent
    in location
    Type
    string | nullable
    Description

    Region from where the transaction was performed

  • Name
    location > town
    Parent
    in location
    Type
    string
    Description

    Town from where the transaction was performed

  • Name
    message
    Type
    string | nullable
    Description

    A customer to send to the customer

  • Name
    name
    Type
    string | nullable
    Description

    A nice name for the transaction (reference param during the request)

  • Name
    pk
    Type
    uuid
    Description
  • Name
    reference
    Type
    string
    Description

    The reference of the transaction for your system, trxId pass during the request

Secure payment dispute events

Dispute events are useful when secure payments involve buyer/seller disagreement or support review.

Event Type: securepay.dispute.evidence_added

Sent when new evidence is added to a dispute.

Typical use cases:

  • update support case activity;
  • notify the other party;
  • trigger internal review.

Evidence will be referenced by ID or secure URL, not embedded directly in the webhook payload.

Event Type: securepay.dispute.message_added

Sent when new message is added to a dispute.

Typical use cases:

  • update support case activity;
  • notify the other party;
  • trigger internal review.

Message will be referenced by ID or secure URL, not embedded directly in the webhook payload.

Event Type: securepay.dispute.under_review

Sent when a secure pay transaction dispute is under review by the payment provider.

Tipical use cases:

  • notify the merchant that the dispute is being reviewed;
  • pause any pending actions related to the dispute;
  • prepare for potential dispute resolution outcomes.

Event Type: securepay.dispute.resolved

Sent when a dispute has been resolved.

Typical use cases:

  • close support case;
  • release funds;
  • refund buyer;
  • update secure payment status.

Object schema

This is the schema of the data.object field in the webhook event payload:

  • Name
    created_at
    Type
    date-time
    Required
    required
    Description
  • Name
    id
    Type
    integer
    Required
    required
    Description
  • Name
    message
    Type
    string
    Required
    required
    Description
  • Name
    metadata
    Type
    undefined
    Required
    required
    Description
  • Name
    nbr_decisions
    Type
    integer
    Required
    required
    Description
  • Name
    nbr_evidences
    Type
    integer
    Required
    required
    Description
  • Name
    nbr_messages
    Type
    integer
    Required
    required
    Description
  • Name
    opened_by_id
    Type
    string
    Required
    required
    Description
  • Name
    opened_by_type
    Type
    string
    Required
    required
    Description
    • merchant - Merchant user
    • buyer - Buyer
    • system - System
    • admin - Admin
    • api - API
    • provider_webhook - Provider webhook
  • Name
    reason
    Type
    string
    Required
    required
    Description
    • ITEM_NOT_RECEIVED - Item not received
    • ITEM_NOT_AS_DESCRIBED - Item not as described
    • ITEM_DAMAGED - Item damaged
    • DUPLICATE_CHARGE - Duplicate charge
    • FRAUDULENT_CHARGE - Fraudulent charge
    • UNAUTHORIZED - Unauthorized
    • OTHER - Other
  • Name
    resolution
    Type
    string
    Required
    required
    Description
    • release_to_merchant - Release to merchant
    • refund_to_payer - Refund to payer
    • partial_release_partial_refund - Partial release/refund
    • cancel_dispute - Cancel dispute
  • Name
    resolved_at
    Type
    date-time | nullable
    Required
    required
    Description
  • Name
    resolved_by
    Type
    string
    Required
    required
    Description
  • Name
    status
    Type
    string
    Required
    required
    Description
    • no_dispute - No dispute
    • dispute_opened - Dispute opened
    • under_review - Under review
    • resolved_release - Resolved: release
    • resolved_refund - Resolved: refund
    • resolved_partial - Resolved: partial
  • Name
    transaction
    Type
    string
    Required
    required
    Description
  • Name
    updated_at
    Type
    date-time
    Required
    required
    Description