SenroPayDevelopers
SENROPAY DEVELOPER PLATFORM

Build your
payment flow.

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.

Server to serverScoped merchant credentials
Idempotent writesOne key per business request
Signed notificationsVerify, persist, then reconcile
Start with the sandbox

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.

01 / GET STARTED

Your first payment request

Create a sandbox request from your server. A successful HTTP response saves the request; it does not prove that funds were collected.

  1. Get an approved sandbox merchant

    SenroPay operations configures the merchant route, limits and scoped API key. Keep the key in your server’s secret manager.

  2. Send a small test request

    Use an original idempotency key and save the returned payment ID with your order. This example requests KES 1.00.

  3. Read the saved result

    Complete the separately authorised private checkout, then read the payment. Match merchant, amount, currency and final status before fulfilling once.

POST /payments · cURL
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.

STAGING BASE URLhttps://merchant-api-staging.senropay.com/api/merchant/v1
02 / CONNECT SAFELY

Credentials belong on your server

Use the merchant key issued for your approved merchant. Requests are scoped to that merchant; another merchant’s resources return a not-found response.

MERCHANT API

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.

WRITE REQUESTS

Stable idempotency keys

Idempotency-Key: order-1001-create

Use 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.

03 / PAYMENT LIFECYCLE

A request is the beginning

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.

1

Create

Persist the request key and returned payment ID with the original order.

2

Complete checkout

Use the returned private sandbox checkout with the matching merchant or authorised operations role.

3

Confirm status

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.

04 / MOBILE MONEY

M-Pesa, with explicit confirmation

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.

Read capability first

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.

Confirm once, then inspect

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.

05 / KEEP ORDERS IN SYNC

Verify every notification

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.

Signature header
SenroPay-Signature: t=<unix-seconds>,v1=<hex-hmac-sha256>
SenroPay-Event-Id: <event-id>
  1. Keep the exact request bytes

    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.

  2. Check freshness and identity

    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.

  3. Commit before acknowledging

    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.

06 / RELEASED CONTRACT

API reference

15 documented operations · OpenAPI 3.0.3 · version 2026-10-19. Every operation uses the same scoped merchant bearer key.

15 operations

POST/payments

Create a payment

Path and request headers
FieldType / locationRequirement
Idempotency-Key
Required
string / headerMinimum length: 8 · Maximum length: 128
JSON request body
FieldType / locationRequirement
amount
Required
integerMinimum: 1 · Maximum: 100000000
currency
Required
stringOne of: KES, USD, EUR, GBP
descriptionstringMaximum length: 160
Response codes
StatusMeaning
200Current saved resource, or idempotent replay
201Request saved; inspect resource status. A response is not confirmation of captured/refunded funds.
defaultError; 429 includes Retry-After. Retain the same idempotency key after timeouts.
GET/payments/{payment_id}

Read a payment

Path and request headers
FieldType / locationRequirement
payment_id
Required
string / pathPattern: ^[A-Za-z0-9_-]{8,80}$
Response codes
StatusMeaning
200Current saved resource, or idempotent replay
defaultError; 429 includes Retry-After. Retain the same idempotency key after timeouts.
POST/payments/{payment_id}/refunds

Create a refund

Path and request headers
FieldType / locationRequirement
payment_id
Required
string / pathPattern: ^[A-Za-z0-9_-]{8,80}$
Idempotency-Key
Required
string / headerMinimum length: 8 · Maximum length: 128
JSON request body
FieldType / locationRequirement
amount
Required
integerMinimum: 1 · Maximum: 100000000
reasonstringMaximum length: 200
Response codes
StatusMeaning
200Current saved resource, or idempotent replay
201Request saved; inspect resource status. A response is not confirmation of captured/refunded funds.
defaultError; 429 includes Retry-After. Retain the same idempotency key after timeouts.
GET/refunds/{refund_id}

Read a refund

Path and request headers
FieldType / locationRequirement
refund_id
Required
string / pathPattern: ^[A-Za-z0-9_-]{8,80}$
Response codes
StatusMeaning
200Current saved resource, or idempotent replay
defaultError; 429 includes Retry-After. Retain the same idempotency key after timeouts.
GET/collection-options

Read the currently approved masked payer and collection capability

Response codes
StatusMeaning
200Saved current state; no inference of settled funds.
defaultError; 429 includes Retry-After. Retain the same idempotency key after timeouts.
GET/collections

List the newest 25 scoped collections

Use collections/search with next_cursor for subsequent pages.

Response codes
StatusMeaning
200Saved current state; no inference of settled funds.
defaultError; 429 includes Retry-After. Retain the same idempotency key after timeouts.
POST/collections

Create an expiring private checkout link

Persist 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.

Path and request headers
FieldType / locationRequirement
Idempotency-Key
Required
string / headerPattern: ^[\w:.\-]{8,128}$ · Minimum length: 8 · Maximum length: 128
JSON request body
FieldType / locationRequirement
amount
Required
integerMinimum: 100 · Maximum: 10000 · Multiple of: 100
currency
Required
stringOne of: KES
description
Required
stringMinimum length: 1 · Maximum length: 160
merchant_reference
Required
stringPattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]{3,79}$
payer_id
Required
stringPattern: ^dpp_[a-f0-9]{24}$
expires_inintegerMinimum: 300 · Maximum: 86400 · Default: 1800
Response codes
StatusMeaning
200Saved current state; no inference of settled funds.
201Collection intent saved; no provider prompt sent.
defaultError; 429 includes Retry-After. Retain the same idempotency key after timeouts.
POST/collections/search

Read the next scoped collection page

Path and request headers
FieldType / locationRequirement
Idempotency-Key
Required
string / headerPattern: ^[\w:.\-]{8,128}$ · Minimum length: 8 · Maximum length: 128
JSON request body
FieldType / locationRequirement
cursor
Required
stringPattern: ^dci_[a-f0-9]{24}$
Response codes
StatusMeaning
200Saved current state; no inference of settled funds.
defaultError; 429 includes Retry-After. Retain the same idempotency key after timeouts.
GET/collections/{collection_id}

Read saved collection status, checkout and recent return requests

A GET never calls a provider. The API key is scoped to one merchant. Read remains available during a processing pause.

Path and request headers
FieldType / locationRequirement
collection_id
Required
string / pathPattern: ^dci_[a-f0-9]{24}$
Response codes
StatusMeaning
200Saved current state; no inference of settled funds.
defaultError; 429 includes Retry-After. Retain the same idempotency key after timeouts.
POST/collections/{collection_id}/confirm

Confirm collection

Revalidate eligibility, payer, pricing and risk; reserve once before sending STK. Lost or ambiguous responses never authorize a replacement prompt. Retries recover the original.

Path and request headers
FieldType / locationRequirement
collection_id
Required
string / pathPattern: ^dci_[a-f0-9]{24}$
Idempotency-Key
Required
string / headerPattern: ^[\w:.\-]{8,128}$ · Minimum length: 8 · Maximum length: 128

Send an empty JSON object: {}.

Response codes
StatusMeaning
200Saved current state; no inference of settled funds.
defaultError; 429 includes Retry-After. Retain the same idempotency key after timeouts.
POST/collections/{collection_id}/sync

Sync collection

Query only the original request. Query calls have a 15-second cooldown. Missing acknowledgement blocks queries and requires operations investigation; no resubmission.

Path and request headers
FieldType / locationRequirement
collection_id
Required
string / pathPattern: ^dci_[a-f0-9]{24}$
Idempotency-Key
Required
string / headerPattern: ^[\w:.\-]{8,128}$ · Minimum length: 8 · Maximum length: 128

Send an empty JSON object: {}.

Response codes
StatusMeaning
200Saved current state; no inference of settled funds.
defaultError; 429 includes Retry-After. Retain the same idempotency key after timeouts.
POST/collections/{collection_id}/cancel

Cancel collection

Cancel an unused link. Submitted collections cannot be cancelled through this operation.

Path and request headers
FieldType / locationRequirement
collection_id
Required
string / pathPattern: ^dci_[a-f0-9]{24}$
Idempotency-Key
Required
string / headerPattern: ^[\w:.\-]{8,128}$ · Minimum length: 8 · Maximum length: 128
JSON request body
FieldType / locationRequirement
reason
Required
stringMinimum length: 10 · Maximum length: 500
Response codes
StatusMeaning
200Saved current state; no inference of settled funds.
defaultError; 429 includes Retry-After. Retain the same idempotency key after timeouts.
POST/collections/{collection_id}/returns

Request product-specific refund or reversal review

Requires 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.

Path and request headers
FieldType / locationRequirement
collection_id
Required
string / pathPattern: ^dci_[a-f0-9]{24}$
Idempotency-Key
Required
string / headerPattern: ^[\w:.\-]{8,128}$ · Minimum length: 8 · Maximum length: 128
JSON request body
FieldType / locationRequirement
kind
Required
stringOne of: refund, reversal
amount
Required
integerMinimum: 1 · Maximum: 10000
reason
Required
stringMinimum length: 10 · Maximum length: 500
Response codes
StatusMeaning
200Saved current state; no inference of settled funds.
defaultError; 429 includes Retry-After. Retain the same idempotency key after timeouts.
GET/collection-returns/{return_id}

Read the saved return review status

Path and request headers
FieldType / locationRequirement
return_id
Required
string / pathPattern: ^dcr_[a-f0-9]{20}$
Response codes
StatusMeaning
200Saved current state; no inference of settled funds.
defaultError; 429 includes Retry-After. Retain the same idempotency key after timeouts.
POST/collection-returns/{return_id}/decision

Cancel the API key’s own pending return request

Only 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.

Path and request headers
FieldType / locationRequirement
return_id
Required
string / pathPattern: ^dcr_[a-f0-9]{20}$
Idempotency-Key
Required
string / headerPattern: ^[\w:.\-]{8,128}$ · Minimum length: 8 · Maximum length: 128
JSON request body
FieldType / locationRequirement
action
Required
stringOne of: cancel
reason
Required
stringMinimum length: 10 · Maximum length: 500
Response codes
StatusMeaning
200Saved current state; no inference of settled funds.
defaultError; 429 includes Retry-After. Retain the same idempotency key after timeouts.

Download the complete OpenAPI contract

07 / RECOVER DELIBERATELY

Errors, limits and retries

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.

Common API responses and next steps
ResponseMeaningNext step
400 / 413 / 415Invalid, oversized or unsupported request bodyCheck the contract, JSON content type and 4 KiB body budget.
401Missing, invalid or revoked merchant keyCheck the server-side key and merchant environment.
403Browser origin, scope, merchant policy or permission restrictionUse a server integration and review your enabled policy.
404Unknown endpoint or resource outside the merchant scopeVerify the exact saved resource ID and merchant.
409Conflicting request or state transitionRead the original resource; preserve its request identity.
429Request budget reachedRespect Retry-After; retain the original key for a write.
502 / 503 / timeoutService unavailable or uncertain upstream outcomeQuery 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.

08 / PLAN YOUR INTEGRATION

What is available today

SenroPay integration availability
CapabilityCurrent availability
Scoped server API and signed notificationsApproved sandbox merchants
Card payment and refund journeyDedicated Fauxpay sandbox configuration
M-Pesa collection intents and checkoutApproved Daraja sandbox payer and explicit confirmation
Customer checkoutPrivate staging access with matching merchant or operations scope
M-Pesa refund / reversal executionUnavailable; review-record endpoints only
Production merchant API and public checkoutPending production rollout and provider acceptance
Maintained SDK packages and e-commerce pluginsPlanned; this portal publishes the contract and reference examples
Crypto and stablecoin railsFuture scope

Ready to build in the sandbox?

Tell us your integration flow, currency and test requirements.

Talk to SenroPay