Payment completed

Authorizations

Authorization

string

header

required

The API key to use for authentication

Body

application/json

Payment Schema

Webhook payload for payment.completed events

data

object

required

Show child attributes

data.id

string

required

Unique identifier for the transaction, prefixed with 'trxn_'

Maximum string length: 255

Example:

"trxn_YGZBY32PBBavYbhL"

data.productId

string | null

required

Maximum string length: 255

data.customerId

string

required

Unique identifier for the customer, prefixed with 'cus_'. Unique identifier for the customer, prefixed with 'cus_'

Required string length: 4 - 255

Example:

"cus_GqfKXLmg61LURZhB"

data.object

string

required

Example:

"transaction"

data.environment

enum<string>

required

The environment of the transaction. Either 'sandbox' or 'production'

Available options:

sandbox,

production

Example:

"sandbox"

data.currency

string

required

The transaction currency

Example:

"KES"

data.amount

number

required

Transaction amount in cents (e.g., 1000 = KES 10.00)

Example:

1000

data.description

string

required

Human-readable description of the transaction purpose

Example:

"Payment for Order #12345 - Premium Subscription"

data.phoneNumber

string

required

Safaricom phone number in local (e.g., 0712345678, 0110123456) or international (e.g., 254712345678, 254110123456) format, transformed to 254XXXXXXXXX for M-PESA STK Push. Supports all Safaricom prefixes (070X, 074X, 0757–0759, 0768–0769, 079X, 0110–0115).

Example:

"254712345678"

data.status

enum<string>

required

Current status of the transaction. Possible values: pending, completed, failed, refunded

Available options:

pending,

completed,

failed,

refunded

Example:

"completed"

data.type

enum<string>

required

The type of transaction

Available options:

payment

Example:

"payment"

data.receiptNumber

string | null

required

The M-Pesa receipt number

Maximum string length: 50

Example:

"QMF7MBB5ED"

data.processedAt

string | null

required

Timestamp when the transaction was processed (ISO 8601 format)

Example:

"2024-12-19T10:30:00.000Z"

data.paidAt

string | null

required

Timestamp when the transaction was successfully paid (ISO 8601 format)

Example:

"2024-12-19T10:32:00.000Z"

data.failedAt

string | null

required

Timestamp when the transaction failed (ISO 8601 format)

Example:

"2024-12-19T10:33:00.000Z"

data.failureReason

string | null

required

The transaction decline reason

Example:

"Insufficient balance"

data.metadata

object

required

Key-value object allowing you to store additional information.

Key Requirements:

Must be a string
Maximum length of 40 characters

Value Types:

String (maximum 500 characters)
Integer
Floating-point number
Boolean

Limits:

Maximum of 50 key-value pairs

Show child attributes

data.metadata.{key}

Maximum string length: 500

Example:

{
  "user_preference": "dark_mode",
  "last_login": 1640995200,
  "is_premium": true,
  "account_balance": 1250.75,
  "notifications_enabled": false
}

data.createdAt

string

required

Timestamp when the transaction was created (ISO 8601 format)

Example:

"2024-12-19T10:25:00.000Z"

data.source

enum<string>

required

The source of the transaction. Either 'api' or 'dashboard'

Available options:

api,

dashboard,

checkout

Example:

"api"

Example:

{
  "id": "trxn_ABC123DEF456GHI",
  "productId": "prod_ABC123DEF456GHI",
  "customerId": "cus_MNO345PQR678STU",
  "object": "transaction",
  "environment": "development",
  "type": "payment",
  "amount": 1000,
  "description": "Payment for Order #12345 - Premium Subscription",
  "currency": "KES",
  "status": "completed",
  "phoneNumber": "254712345678",
  "receiptNumber": "QMF7MBB5ED",
  "fee": 100,
  "netAmount": 900,
  "failureReason": null,
  "metadata": {},
  "source": "api",
  "processedAt": "2024-12-19T10:30:00.000Z",
  "createdAt": "2024-12-19T10:25:00.000Z",
  "paidAt": "2024-12-19T10:32:00.000Z",
  "failedAt": null
}

timestamp

string

required

ISO 8601 timestamp when the event occurred

Example:

"2021-01-01T00:00:00Z"

type

string

default:payment.completed

Event type for payment.completed

Example:

"payment.completed"

object

string

default:event

Object type, always "event"

Example:

"event"

Response

200

Webhook received successfully

Getting Started

APIs

Authorizations

Body

Response