Bearer authentication
Authorization: Bearer sp_hs_test_…The scoped merchant API uses sp_hs_test_ keys. Simulator keys beginning sp_test_ belong to a separate product and cannot call these endpoints. Refund writes need a refund-enabled key.
One clear contract for payment requests, refunds and M-Pesa collections. Start in the sandbox, keep every request traceable, and confirm the outcome before you fulfil an order.
This reference covers the released staging API. Production merchant access and public customer checkout are not enabled. Your approved merchant policy, processor route and permissions determine which requests are available.
Create a sandbox request from your server. A successful HTTP response saves the request; it does not prove that funds were collected.
SenroPay operations configures the merchant route, limits and scoped API key. Keep the key in your server’s secret manager.
Use an original idempotency key and save the returned payment ID with your order. This example requests KES 1.00.
Complete the separately authorised private checkout, then read the payment. Match merchant, amount, currency and final status before fulfilling once.
curl --request POST \
'https://merchant-api-staging.senropay.com/api/merchant/v1/payments' \
--header "Authorization: Bearer $SENROPAY_API_KEY" \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: order-1001-create' \
--data '{"amount":100,"currency":"KES","description":"Sandbox order 1001"}'The key above is an environment-variable reference. Never place an actual merchant key in browser code, a public example or source control.
https://merchant-api-staging.senropay.com/api/merchant/v1Use the merchant key issued for your approved merchant. Requests are scoped to that merchant; another merchant’s resources return a not-found response.
Authorization: Bearer sp_hs_test_…The scoped merchant API uses sp_hs_test_ keys. Simulator keys beginning sp_test_ belong to a separate product and cannot call these endpoints. Refund writes need a refund-enabled key.
Idempotency-Key: order-1001-createUse 8–128 letters, digits, underscores, colons, dots or hyphens. Retain the original key and identical body after a timeout. A changed request under the same key conflicts.
Browser-origin requests are rejected. The owned merchant API handles its internal service transport; your integration supplies the merchant bearer key, documented headers and request body.
Amounts use integer minor units: 100 = KES 1.00. A create response, checkout redirect or webhook snapshot is not an instruction to fulfil an order.
Persist the request key and returned payment ID with the original order.
Use the returned private sandbox checkout with the matching merchant or authorised operations role.
Read the saved payment and verify the original merchant, amount, currency and succeeded status.
Use POST /payments/{payment_id}/refunds for supported Hyperswitch sandbox refunds. Refund amounts must stay within the refundable balance. Give each refund its own stable key and read the refund until its outcome is terminal.
Current self-hosted card testing uses the dedicated Fauxpay sandbox configuration, approved KES routes and an upper limit of KES 100.00. Contract-level currency and amount fields do not override your merchant’s enabled route or limits.
Create an expiring collection checkout for an independently approved Daraja sandbox payer. The merchant reference identifies your order; the saved intent keeps its original payer and terms.
GET /collection-options returns the current approved masked payer, limits and available actions. Collection requests use whole-shilling KES amounts: 100–10,000 minor units, or KES 1–100.
Creating a collection sends no provider prompt. Confirmation can submit at most one STK request for that collection. On uncertainty, keep the original request and use its status or explicit sync action.
A successful collection requires an authenticated Daraja query to agree with the retained callback. Status reads do not query the provider. Collection queries are explicit; the background timer does not automatically query Daraja.
Collection return endpoints create refund or reversal review records. They do not execute M-Pesa refunds or reversals. A pending review or blocked_unsupported decision does not mean money was returned.
SenroPay delivers signed events at least once. Your receiver must handle duplicates and out-of-order delivery, store accepted events durably, and reconcile against current resource state.
SenroPay-Signature: t=<unix-seconds>,v1=<hex-hmac-sha256>
SenroPay-Event-Id: <event-id>Calculate HMAC-SHA256 over the UTF-8 timestamp, a full stop and the unmodified request body, using your webhook signing secret. Verify the signature before parsing JSON.
The reference verifier accepts up to five minutes of age and 30 seconds of future clock skew. Match the header event ID to the JSON ID, merchant and sandbox environment.
Persist event ID and body hash atomically, reject conflicting reuse of an ID, and acknowledge only after durable commit. Fetch the latest payment, refund or collection before any order transition.
Download the Node.js signature verifier
Operations approves exact HTTPS callback destinations and configures the endpoint. The current sandbox timer runs every five minutes and processes at most two outbound events per batch; this cadence is a sandbox limit, not a production delivery SLA.
15 documented operations · OpenAPI 3.0.3 · version 2026-10-19. Every operation uses the same scoped merchant bearer key.
15 operations
/payments| Field | Type / location | Requirement |
|---|---|---|
Idempotency-KeyRequired | string / header | Minimum length: 8 · Maximum length: 128 |
| Field | Type / location | Requirement |
|---|---|---|
amountRequired | integer | Minimum: 1 · Maximum: 100000000 |
currencyRequired | string | One of: KES, USD, EUR, GBP |
description | string | Maximum length: 160 |
| Status | Meaning |
|---|---|
200 | Current saved resource, or idempotent replay |
201 | Request saved; inspect resource status. A response is not confirmation of captured/refunded funds. |
default | Error; 429 includes Retry-After. Retain the same idempotency key after timeouts. |
/payments/{payment_id}| Field | Type / location | Requirement |
|---|---|---|
payment_idRequired | string / path | Pattern: ^[A-Za-z0-9_-]{8,80}$ |
| Status | Meaning |
|---|---|
200 | Current saved resource, or idempotent replay |
default | Error; 429 includes Retry-After. Retain the same idempotency key after timeouts. |
/payments/{payment_id}/refunds| Field | Type / location | Requirement |
|---|---|---|
payment_idRequired | string / path | Pattern: ^[A-Za-z0-9_-]{8,80}$ |
Idempotency-KeyRequired | string / header | Minimum length: 8 · Maximum length: 128 |
| Field | Type / location | Requirement |
|---|---|---|
amountRequired | integer | Minimum: 1 · Maximum: 100000000 |
reason | string | Maximum length: 200 |
| Status | Meaning |
|---|---|
200 | Current saved resource, or idempotent replay |
201 | Request saved; inspect resource status. A response is not confirmation of captured/refunded funds. |
default | Error; 429 includes Retry-After. Retain the same idempotency key after timeouts. |
/refunds/{refund_id}| Field | Type / location | Requirement |
|---|---|---|
refund_idRequired | string / path | Pattern: ^[A-Za-z0-9_-]{8,80}$ |
| Status | Meaning |
|---|---|
200 | Current saved resource, or idempotent replay |
default | Error; 429 includes Retry-After. Retain the same idempotency key after timeouts. |
/collection-options| Status | Meaning |
|---|---|
200 | Saved current state; no inference of settled funds. |
default | Error; 429 includes Retry-After. Retain the same idempotency key after timeouts. |
/collectionsUse collections/search with next_cursor for subsequent pages.
| Status | Meaning |
|---|---|
200 | Saved current state; no inference of settled funds. |
default | Error; 429 includes Retry-After. Retain the same idempotency key after timeouts. |
/collectionsPersist the exact request and key. Merchant reference is unique per merchant. No arbitrary phone, callback or return URL is accepted. The approved payer and order terms are immutable.
| Field | Type / location | Requirement |
|---|---|---|
Idempotency-KeyRequired | string / header | Pattern: ^[\w:.\-]{8,128}$ · Minimum length: 8 · Maximum length: 128 |
| Field | Type / location | Requirement |
|---|---|---|
amountRequired | integer | Minimum: 100 · Maximum: 10000 · Multiple of: 100 |
currencyRequired | string | One of: KES |
descriptionRequired | string | Minimum length: 1 · Maximum length: 160 |
merchant_referenceRequired | string | Pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]{3,79}$ |
payer_idRequired | string | Pattern: ^dpp_[a-f0-9]{24}$ |
expires_in | integer | Minimum: 300 · Maximum: 86400 · Default: 1800 |
| Status | Meaning |
|---|---|
200 | Saved current state; no inference of settled funds. |
201 | Collection intent saved; no provider prompt sent. |
default | Error; 429 includes Retry-After. Retain the same idempotency key after timeouts. |
/collections/search| Field | Type / location | Requirement |
|---|---|---|
Idempotency-KeyRequired | string / header | Pattern: ^[\w:.\-]{8,128}$ · Minimum length: 8 · Maximum length: 128 |
| Field | Type / location | Requirement |
|---|---|---|
cursorRequired | string | Pattern: ^dci_[a-f0-9]{24}$ |
| Status | Meaning |
|---|---|
200 | Saved current state; no inference of settled funds. |
default | Error; 429 includes Retry-After. Retain the same idempotency key after timeouts. |
/collections/{collection_id}A GET never calls a provider. The API key is scoped to one merchant. Read remains available during a processing pause.
| Field | Type / location | Requirement |
|---|---|---|
collection_idRequired | string / path | Pattern: ^dci_[a-f0-9]{24}$ |
| Status | Meaning |
|---|---|
200 | Saved current state; no inference of settled funds. |
default | Error; 429 includes Retry-After. Retain the same idempotency key after timeouts. |
/collections/{collection_id}/confirmRevalidate eligibility, payer, pricing and risk; reserve once before sending STK. Lost or ambiguous responses never authorize a replacement prompt. Retries recover the original.
| Field | Type / location | Requirement |
|---|---|---|
collection_idRequired | string / path | Pattern: ^dci_[a-f0-9]{24}$ |
Idempotency-KeyRequired | string / header | Pattern: ^[\w:.\-]{8,128}$ · Minimum length: 8 · Maximum length: 128 |
Send an empty JSON object: {}.
| Status | Meaning |
|---|---|
200 | Saved current state; no inference of settled funds. |
default | Error; 429 includes Retry-After. Retain the same idempotency key after timeouts. |
/collections/{collection_id}/syncQuery only the original request. Query calls have a 15-second cooldown. Missing acknowledgement blocks queries and requires operations investigation; no resubmission.
| Field | Type / location | Requirement |
|---|---|---|
collection_idRequired | string / path | Pattern: ^dci_[a-f0-9]{24}$ |
Idempotency-KeyRequired | string / header | Pattern: ^[\w:.\-]{8,128}$ · Minimum length: 8 · Maximum length: 128 |
Send an empty JSON object: {}.
| Status | Meaning |
|---|---|
200 | Saved current state; no inference of settled funds. |
default | Error; 429 includes Retry-After. Retain the same idempotency key after timeouts. |
/collections/{collection_id}/cancelCancel an unused link. Submitted collections cannot be cancelled through this operation.
| Field | Type / location | Requirement |
|---|---|---|
collection_idRequired | string / path | Pattern: ^dci_[a-f0-9]{24}$ |
Idempotency-KeyRequired | string / header | Pattern: ^[\w:.\-]{8,128}$ · Minimum length: 8 · Maximum length: 128 |
| Field | Type / location | Requirement |
|---|---|---|
reasonRequired | string | Minimum length: 10 · Maximum length: 500 |
| Status | Meaning |
|---|---|
200 | Saved current state; no inference of settled funds. |
default | Error; 429 includes Retry-After. Retain the same idempotency key after timeouts. |
/collections/{collection_id}/returnsRequires a refund-enabled key and matched successful collection. Open and capability-blocked requests cannot exceed the collection amount. This does not execute a refund/reversal, reserve ledger funds or mark money refunded.
| Field | Type / location | Requirement |
|---|---|---|
collection_idRequired | string / path | Pattern: ^dci_[a-f0-9]{24}$ |
Idempotency-KeyRequired | string / header | Pattern: ^[\w:.\-]{8,128}$ · Minimum length: 8 · Maximum length: 128 |
| Field | Type / location | Requirement |
|---|---|---|
kindRequired | string | One of: refund, reversal |
amountRequired | integer | Minimum: 1 · Maximum: 10000 |
reasonRequired | string | Minimum length: 10 · Maximum length: 500 |
| Status | Meaning |
|---|---|
200 | Saved current state; no inference of settled funds. |
default | Error; 429 includes Retry-After. Retain the same idempotency key after timeouts. |
/collection-returns/{return_id}| Field | Type / location | Requirement |
|---|---|---|
return_idRequired | string / path | Pattern: ^dcr_[a-f0-9]{20}$ |
| Status | Meaning |
|---|---|
200 | Saved current state; no inference of settled funds. |
default | Error; 429 includes Retry-After. Retain the same idempotency key after timeouts. |
/collection-returns/{return_id}/decisionOnly the original requester can cancel before independent review. Staff rejection/capability-block decisions use the signed-in console and separate reviewer. There is no execute endpoint.
| Field | Type / location | Requirement |
|---|---|---|
return_idRequired | string / path | Pattern: ^dcr_[a-f0-9]{20}$ |
Idempotency-KeyRequired | string / header | Pattern: ^[\w:.\-]{8,128}$ · Minimum length: 8 · Maximum length: 128 |
| Field | Type / location | Requirement |
|---|---|---|
actionRequired | string | One of: cancel |
reasonRequired | string | Minimum length: 10 · Maximum length: 500 |
| Status | Meaning |
|---|---|
200 | Saved current state; no inference of settled funds. |
default | Error; 429 includes Retry-After. Retain the same idempotency key after timeouts. |
Use the HTTP status and the returned error.message to diagnose the request. A transport failure or ambiguous response is not proof that the original command failed.
| Response | Meaning | Next step |
|---|---|---|
| 400 / 413 / 415 | Invalid, oversized or unsupported request body | Check the contract, JSON content type and 4 KiB body budget. |
| 401 | Missing, invalid or revoked merchant key | Check the server-side key and merchant environment. |
| 403 | Browser origin, scope, merchant policy or permission restriction | Use a server integration and review your enabled policy. |
| 404 | Unknown endpoint or resource outside the merchant scope | Verify the exact saved resource ID and merchant. |
| 409 | Conflicting request or state transition | Read the original resource; preserve its request identity. |
| 429 | Request budget reached | Respect Retry-After; retain the original key for a write. |
| 502 / 503 / timeout | Service unavailable or uncertain upstream outcome | Query the original resource before any additional financial command. |
The current budgets are 60 requests per minute per merchant across its keys and 300 per minute across the staging ingress receiver. Resource and policy validation can impose tighter limits.
| Capability | Current availability |
|---|---|
| Scoped server API and signed notifications | Approved sandbox merchants |
| Card payment and refund journey | Dedicated Fauxpay sandbox configuration |
| M-Pesa collection intents and checkout | Approved Daraja sandbox payer and explicit confirmation |
| Customer checkout | Private staging access with matching merchant or operations scope |
| M-Pesa refund / reversal execution | Unavailable; review-record endpoints only |
| Production merchant API and public checkout | Pending production rollout and provider acceptance |
| Maintained SDK packages and e-commerce plugins | Planned; this portal publishes the contract and reference examples |
| Crypto and stablecoin rails | Future scope |
Tell us your integration flow, currency and test requirements.