mpesa

type APIError struct {
	RequestID    string `json:"requestId"`
	ErrorCode    string `json:"errorCode"`
	ErrorMessage string `json:"errorMessage"`
}

type AccountBalance struct {
	Name      string
	Currency  string
	Available int64
	Uncleared int64
	Reserved  int64
}

type AccountBalanceRequest struct {
	// PartyA defaults to the configured collection shortcode.
	PartyA         uint
	IdentifierType PartyIdentifierType
	Remarks        string
	URLs           AsyncURLs
}

type AccountResolver interface {
	ResolveAccount(accountNumber string) (accountName string, found bool, err error)
}

type AsyncAck struct {
	OriginatorConversationID string `json:"OriginatorConversationID"`
	ConversationID           string `json:"ConversationID"`
	ResponseCode             string `json:"ResponseCode"`
	ResponseDescription      string `json:"ResponseDescription"`
}

type AsyncOutcome struct {
	Kind OutcomeKind

	// Retryable reports whether the identical request may succeed if resent.
	// For a request with a client-supplied idempotency key this means reusing
	// the same key, never minting a fresh one.
	Retryable bool

	// Message is a short operator-facing summary.
	Message string
}

type AsyncURLs struct {
	ResultURL       string
	QueueTimeOutURL string
}

type B2BRequest struct {
	// PartyA defaults to the configured collection shortcode — the float this
	// package's collections land in is the one every envelope-B command here
	// is expected to move money out of.
	PartyA uint

	// PartyB is the receiving paybill or till. Ignored by PayTaxToKRA (always
	// 572572) and by BusinessPayToBulk when zero (defaults to the configured
	// disbursement shortcode).
	PartyB uint

	AmountKES int64

	// AccountReference is at most 13 characters — one more than STK's 12, per
	// Daraja's own example (ACC#03929/4yu).
	AccountReference string

	// Requester is the consumer's MSISDN this payment is made on behalf of.
	// Optional; populate it whenever the B2B payment exists because of a
	// specific borrower, e.g. paying a supplier directly for purpose-bound
	// lending.
	Requester string

	Remarks string

	URLs AsyncURLs
}

type B2CRequest struct {
	// Command defaults to CommandBusinessPayment.
	Command PayoutCommand

	// OriginatorConversationID is caller-supplied and is B2C's native
	// idempotency key — Daraja rejects reuse with 500.002.1001, which means
	// "this request already reached us", never a reason to retry with a
	// fresh ID. See §7 of the plan.
	OriginatorConversationID string

	// PartyA defaults to the configured disbursement shortcode.
	PartyA uint

	// PartyB is the recipient MSISDN: 12 digits, no '+'.
	PartyB string

	AmountKES int64

	// Remarks is 2-100 characters.
	Remarks string

	// Occasion is 1-100 characters when set; optional.
	Occasion string

	URLs AsyncURLs
}

type C2BNotification struct {
	TransactionType   string
	TransID           string
	TransTime         string
	TransAmountMinor  int64
	BusinessShortCode string

	// BillRefNumber is the account number the payer typed, and on a shared
	// paybill it is the only thing binding a payment to a loan. It is null for
	// till payments.
	BillRefNumber string

	InvoiceNumber string

	// OrgAccountBalanceMinor is blank on validation and the post-payment
	// balance on confirmation.
	OrgAccountBalanceMinor int64

	// ThirdPartyTransID is ours to set: a validation response may return one,
	// and Daraja echoes it on the matching confirmation.
	ThirdPartyTransID string

	// MSISDN is masked on C2B v2. It cannot be used as a phone number; the
	// unmasked value comes from Pull Transaction.
	MSISDN MaskedMSISDN

	FirstName  string
	MiddleName string
	LastName   string
}

type C2BNotificationWire struct {
	// TransactionType is Safaricom's transaction type, e.g. "Pay Bill" or "Buy Goods".
	TransactionType string `json:"TransactionType" example:"Pay Bill"`
	// TransID is Safaricom's unique receipt number for this payment.
	TransID string `json:"TransID" example:"OEI2AK4Q16"`
	// TransTime is the payment timestamp as YYYYMMDDHHmmss.
	TransTime string `json:"TransTime" example:"20260911120000"`
	// TransAmount is the payment amount in KES, as a decimal string.
	TransAmount string `json:"TransAmount" example:"500.00"`
	// BusinessShortCode is the paybill/till the payment was made to.
	BusinessShortCode string `json:"BusinessShortCode" example:"174379"`
	// BillRefNumber is the account reference the payer typed, exactly as entered.
	BillRefNumber string `json:"BillRefNumber" example:"MV7K3QA9"`
	// InvoiceNumber is an optional invoice reference; usually empty for C2B.
	InvoiceNumber string `json:"InvoiceNumber"`
	// OrgAccountBalance is the shortcode's balance after this transaction, as a decimal string.
	OrgAccountBalance string `json:"OrgAccountBalance" example:"150000.00"`
	// ThirdPartyTransID is echoed back from our validation response, present only on the confirmation callback.
	ThirdPartyTransID string `json:"ThirdPartyTransID"`
	// MSISDN is the payer's phone number.
	MSISDN string `json:"MSISDN" example:"254712345678"`
	// FirstName is the payer's first name as held by Safaricom.
	FirstName string `json:"FirstName"`
	// MiddleName is the payer's middle name as held by Safaricom.
	MiddleName string `json:"MiddleName"`
	// LastName is the payer's last name as held by Safaricom.
	LastName string `json:"LastName"`
}

type C2BPayload struct {
	// TransID is the M-Pesa receipt and the natural idempotency key: a unique
	// index on it makes a duplicate confirmation a no-op rather than a second
	// credit.
	TransID string

	// BillRefNumber is the reference the payer typed. On a shared paybill it
	// is the only thing binding the payment to a loan.
	BillRefNumber string

	// MaskedMSISDN is all a confirmation discloses. The unmasked number comes
	// from Pull Transaction.
	MaskedMSISDN MaskedMSISDN

	ThirdPartyTransID string
	AmountMinor       int64
	PaidAt            time.Time
}

type Callback struct {
	Kind    CallbackKind
	Outcome Outcome
	Result  *Result
}

type CallbackKind string

type Client struct {
	// contains filtered or unexported fields
}

type Config struct {
	Environment Environment

	ConsumerKey    string
	ConsumerSecret string

	// CollectionShortcode receives C2B and M-Pesa Express payments.
	CollectionShortcode uint

	// DisbursementShortcode funds payouts and is the PartyA of balance and
	// reversal queries against the payout side.
	DisbursementShortcode uint

	// Passkey signs the M-Pesa Express password. Issued per shortcode.
	Passkey string

	// InitiatorName is the M-PESA API operator username. InitiatorPassword is
	// its plaintext password, encrypted per call into a SecurityCredential.
	InitiatorName     string
	InitiatorPassword string

	// BaseURL overrides Environment.BaseURL. Tests point it at a stub.
	BaseURL string

	// Certificate overrides the embedded Safaricom certificate. Tests supply
	// one whose private half they hold so a SecurityCredential can be decrypted
	// and checked rather than merely inspected.
	Certificate []byte

	// HttpClient defaults to a client with a 30 second timeout.
	HttpClient HttpClient

	// TokenStore defaults to an in-process store. Deployments with more than
	// one replica should supply a shared one: Daraja invalidates the previous
	// access token on every mint, so per-process caches evict each other.
	TokenStore TokenStore

	// Clock defaults to time.Now. Overridable so timestamp derivation and
	// token expiry are testable.
	Clock func() time.Time
}

type DarajaError struct {
	StatusCode int
	RequestID  string
	Code       string
	Message    string
}

type Environment string

type ExpressCallback struct {
	MerchantRequestID string
	CheckoutRequestID string
	ResultCode        int64
	ResultDesc        string

	// The following are present only on success; CallbackMetadata is absent
	// entirely when the customer did not pay.
	AmountKES     int64
	AmountMinor   int64
	ReceiptNumber string
	Payer         string
	CompletedAt   time.Time
}

type ExpressCallbackBody struct {
	// STKCallback is the actual result payload for one STK push.
	STKCallback ExpressCallbackResult `json:"stkCallback"`
}

type ExpressCallbackEnvelope struct {
	// Body wraps the stkCallback object; Safaricom always nests it one level deep.
	Body ExpressCallbackBody `json:"Body"`
}

type ExpressCallbackMetadataHolder struct {
	// Item is the list of name/value receipt fields (Amount, MpesaReceiptNumber, TransactionDate, PhoneNumber, ...).
	Item []ExpressCallbackMetadataItem `json:"Item"`
}

type ExpressCallbackMetadataItem struct {
	// Name identifies which receipt field this is, e.g. "Amount", "MpesaReceiptNumber".
	Name string `json:"Name" example:"MpesaReceiptNumber"`
	// Value is the field's raw JSON value; its type (string vs number) depends on Name.
	Value json.RawMessage `json:"Value"`
}

type ExpressCallbackResult struct {
	// MerchantRequestID is the ID Safaricom assigned when the STK push was initiated.
	MerchantRequestID string `json:"MerchantRequestID" example:"29115-34620561-1"`
	// CheckoutRequestID is the ID this codebase used to originate the push and correlate the result.
	CheckoutRequestID string `json:"CheckoutRequestID" example:"ws_CO_191220191020363925"`
	// ResultCode is 0 on success; any other value maps through ExpressOutcomeFor to decide retryability.
	ResultCode FlexibleInt64 `json:"ResultCode" example:"0"`
	// ResultDesc is Safaricom's human-readable outcome description.
	ResultDesc string `json:"ResultDesc" example:"The service request is processed successfully."`
	// CallbackMetadata carries the payment receipt details; nil when the customer did not pay.
	CallbackMetadata *ExpressCallbackMetadataHolder `json:"CallbackMetadata"`
}

type ExpressOutcome struct {
	// Retryable reports whether trying again could succeed without anything
	// else changing.
	Retryable bool

	// Operational reports whether this is our problem rather than the payer's.
	// An operational failure must never be surfaced to a borrower as if they
	// did something wrong.
	Operational bool

	// Message is safe to show a borrower. GSM 03.38 characters only, because
	// it may be rendered on a feature phone over USSD or SMS.
	Message string
}

type ExpressPayload struct {
	MerchantRequestID string
	CheckoutRequestID string
	CustomerMessage   string
	PromptedAmountKES int64
}

type ExpressQueryResponse struct {
	ResponseCode        string `json:"ResponseCode"`
	ResponseDescription string `json:"ResponseDescription"`
	MerchantRequestID   string `json:"MerchantRequestID"`
	CheckoutRequestID   string `json:"CheckoutRequestID"`

	// ResultCode is held raw because Daraja sends it as a number, a quoted
	// number, or an alphanumeric code. SFC_IC0003 ("the operator does not
	// exist") is the documented case, and collapsing it into an integer would
	// make an unmappable failure read as success 0.
	ResultCode json.RawMessage `json:"ResultCode"`

	ResultDesc string `json:"ResultDesc"`
}

type ExpressRequest struct {
	// Shortcode defaults to the configured collection shortcode.
	Shortcode uint

	TransactionType TransactionType

	// AmountKES is whole shillings. M-Pesa Express does not accept cents.
	AmountKES int64

	// Payer receives the prompt and is debited. Accepted in any Kenyan format
	// and normalised to 2547XXXXXXXX.
	Payer string

	// CallbackURL receives the result. It must not contain a word Daraja
	// blocks; see AssertCallbackURL.
	CallbackURL string

	// AccountReference is shown to the customer in the prompt. Twelve
	// characters at most.
	AccountReference string

	// TransactionDesc is optional. Thirteen characters at most.
	TransactionDesc string
}

type ExpressResponse struct {
	MerchantRequestID   string `json:"MerchantRequestID"`
	CheckoutRequestID   string `json:"CheckoutRequestID"`
	ResponseCode        string `json:"ResponseCode"`
	ResponseDescription string `json:"ResponseDescription"`
	CustomerMessage     string `json:"CustomerMessage"`

	// Set on some in-band business failures that bypass the HTTP classifier.
	ErrorCode    string `json:"errorCode,omitempty"`
	ErrorMessage string `json:"errorMessage,omitempty"`
}

type FlexibleInt64 int64

type HakikishaRequest struct {
	// AccountNumber is the reference the payer typed on their handset, so it
	// arrives exactly as they typed it.
	AccountNumber string `json:"accountNumber" example:"MV7K3QA9"`

	// ShortCode is the M-Pesa paybill/till the payer is sending to.
	ShortCode string `json:"shortCode" example:"174379"`

	// Timestamp arrives as either a string or a number.
	Timestamp FlexibleInt64 `json:"timestamp" example:"20260911120000"`

	// TransactionID is Safaricom's identifier for this validation request.
	TransactionID string `json:"transactionId" example:"OEI2AK4Q16"`
}

type HakikishaResponse struct {
	// AccountName is shown to the payer on their handset; must identify the obligation, never the borrower. Empty when not found.
	AccountName string `json:"accountName" example:"Microvault Loan MV7K3QA9"`
	// AccountNumber echoes back the reference that was resolved.
	AccountNumber string `json:"accountNumber" example:"MV7K3QA9"`
	// ResponseCode is HakikishaFound ("0") or HakikishaNotFound ("1").
	ResponseCode string `json:"responseCode" example:"0"`
	// ResponseDesc is a short human-readable status, e.g. "Success" or "Account not found".
	ResponseDesc string `json:"responseDesc" example:"Success"`
}

type HttpClient interface {
	Do(req *http.Request) (*http.Response, error)
}

type IDType string

type MaskedMSISDN string

type MemoryTokenStore struct {
	// contains filtered or unexported fields
}

type NumberValidation struct {
	ResponseRefID string
	ResponseCode  string
	Message       string

	// Matched is true only on the documented success code. Anything
	// unrecognised is false.
	Matched bool
}

type Options struct {
	TransactionType TransactionType
	Shortcode       uint

	// TransactionDesc is shown in the prompt. Thirteen characters at most.
	TransactionDesc string
}

type OrgIdentifierType string

type OrgInfoRequest struct {
	IdentifierType OrgIdentifierType
	// Identifier is the till or paybill number, as a string on the wire.
	Identifier string
}

type OrgInfoResponse struct {
	ConversationID        string `json:"ConversationID"`
	ResponseCode          string `json:"ResponseCode"`
	ResponseMessage       string `json:"ResponseMessage"`
	DetailedMessage       string `json:"DetailedMessage"`
	OrganizationShortCode string `json:"OrganizationShortCode"`
	OrganizationName      string `json:"OrganizationName"`
	// ChargeProfileID determines who bears the B2B transaction's cost. The
	// published profile-ID mapping is partial and the documentation's own
	// sample returns an ID absent from it — record it verbatim and map it
	// when known; never fail on an unrecognised value.
	ChargeProfileID string `json:"ChargeProfileID"`
}

type Outcome string

type OutcomeKind string

type Parameters map[string][]string

type PartyIdentifierType string

type PayBillPayload struct {
	Shortcode        uint
	AccountReference string
}

type PayoutCommand string

type PullRegisterRequest struct {
	// Shortcode defaults to the configured collection shortcode.
	Shortcode uint

	// NominatedNumber is the number Safaricom associates with the
	// registration.
	NominatedNumber string

	CallbackURL string
}

type PullRegisterResponse struct {
	ResponseRefID       string `json:"ResponseRefID"`
	ResponseStatus      string `json:"ResponseStatus"`
	ShortCode           string `json:"ShortCode"`
	ResponseDescription string `json:"ResponseDescription"`
}

type PulledTransaction struct {
	TransactionID   string
	CompletedAt     time.Time
	MSISDN          string
	TransactionType string
	BillReference   string
	AmountMinor     int64
	Organization    string
}

type QRRequest struct {
	MerchantName string
	ReferenceNo  string
	AmountKES    int64
	TrxCode      TrxCode

	// CreditPartyIdentifier is the paybill, till or number being paid.
	CreditPartyIdentifier string

	// Size is the image edge in pixels. Defaults to 300.
	Size string
}

type QRResponse struct {
	ResponseCode        string `json:"ResponseCode"`
	RequestID           string `json:"RequestID"`
	ResponseDescription string `json:"ResponseDescription"`

	// QRCode is a base64-encoded PNG. It is returned as it arrived: a library
	// has no business writing files, deriving paths from data, or depending on
	// the process working directory.
	QRCode string `json:"QRCode"`
}

type RawResult struct {
	// ResultType is part of Daraja's envelope; this package does not
	// interpret it, only ResultCode.
	ResultType FlexibleInt64 `json:"ResultType" example:"0"`
	// ResultCode is 0/"0" on success; non-zero (numeric or, for reversals, "R000001"/"R000002") on failure.
	ResultCode json.RawMessage `json:"ResultCode" example:"0"`
	// ResultDesc is Daraja's human-readable outcome description.
	ResultDesc string `json:"ResultDesc" example:"The service request has been accepted successfully."`
	// OriginatorConversationID is the ID this codebase generated when initiating the request.
	OriginatorConversationID string `json:"OriginatorConversationID" example:"29112-34801843-1"`
	// ConversationID is Daraja's own ID for this conversation.
	ConversationID string `json:"ConversationID" example:"AG_20260911_1234567890"`
	// TransactionID is Safaricom's receipt number for the underlying transaction, when one exists.
	TransactionID string `json:"TransactionID" example:"OEI2AK4Q16"`

	// ResultParameters holds the endpoint-specific key/value payload (e.g. balances, receipt details) as a raw array or object; shape depends on the endpoint, decoded by decodeParameters.
	ResultParameters *struct {
		ResultParameter json.RawMessage `json:"ResultParameter"`
	} `json:"ResultParameters"`

	// ReferenceData holds endpoint-specific reference items alongside ResultParameters; same raw array-or-object ambiguity.
	ReferenceData *struct {
		ReferenceItem json.RawMessage `json:"ReferenceItem"`
	} `json:"ReferenceData"`
}

type RegisterURLRequest struct {
	// Shortcode defaults to the configured collection shortcode.
	Shortcode uint

	ResponseType ResponseType

	// ValidationURL is called only when external validation is enabled on the
	// shortcode, which it is not by default. Enabling it is a request to
	// Safaricom, not a setting.
	ValidationURL string

	ConfirmationURL string
}

type RegisterURLResponse struct {
	OriginatorConversationID string `json:"OriginatorCoversationID"`
	ResponseCode             string `json:"ResponseCode"`
	ResponseDescription      string `json:"ResponseDescription"`
}

type ResponseType string

type Result struct {
	ResultType int64

	// ResultCode is the code as Daraja sent it, held as a string rather than an
	// integer because the namespace is not numeric. Reversal failure results
	// carry R000001 and R000002, and folding those into an integer would make
	// an unmappable failure read as success 0. Use ResultCodeInt for the
	// numeric cases and the per-family outcome lookups to classify it.
	ResultCode               string
	ResultDesc               string
	OriginatorConversationID string
	ConversationID           string
	TransactionID            string

	// Parameters holds ResultParameters.ResultParameter.
	Parameters Parameters

	// Reference holds ReferenceData.ReferenceItem.
	Reference Parameters
}

type ResultEnvelope struct {
	// Result is the outcome payload; always nested one level under "Result" by Daraja.
	Result RawResult `json:"Result"`
}

type ResultError struct {
	ResultCode               string
	ResultDesc               string
	ConversationID           string
	OriginatorConversationID string
	TransactionID            string
}

type ResultFamily string

type ReversalIdentifierType string

type ReversalPayload struct {
	TransactionID         string
	OriginalTransactionID string
	AmountMinor           int64
	ChargeMinor           int64

	// CreditPartyPublicName arrives unmasked and with a full name. It belongs
	// in an audit record, never in a log line.
	CreditPartyPublicName string
}

type ReversalRequest struct {
	// TransactionID is the M-Pesa receipt being reversed.
	TransactionID string

	// AmountKES must equal the amount originally received.
	AmountKES int64

	// ReceiverParty defaults to the configured collection shortcode: the
	// shortcode that received the money and will give it back.
	ReceiverParty uint

	Remarks  string
	Occasion string

	URLs AsyncURLs
}

type SimulateRequest struct {
	Shortcode     uint
	CommandID     TransactionType
	AmountKES     int64
	Payer         string
	BillRefNumber string
}

type SimulateResponse struct {
	OriginatorConversationID string `json:"OriginatorCoversationID"`
	ConversationID           string `json:"ConversationID"`
	ResponseCode             string `json:"ResponseCode"`
	ResponseDescription      string `json:"ResponseDescription"`
}

type TokenStore interface {
	Get(ctx context.Context, key string) (token string, expiresAt time.Time, ok bool)
	Set(ctx context.Context, key, token string, expiresAt time.Time) error
	Delete(ctx context.Context, key string) error
}

type TransactionStatusRequest struct {
	// TransactionID is the M-Pesa receipt. Supply this or
	// OriginalConversationID.
	TransactionID string

	// OriginalConversationID identifies a request whose receipt we never saw.
	OriginalConversationID string

	// PartyA defaults to the configured collection shortcode.
	PartyA         uint
	IdentifierType PartyIdentifierType

	Remarks  string
	Occasion string

	URLs AsyncURLs
}

type TransactionType string

type TrxCode string

type ValidationPolicy string

type ValidationResponse struct {
	// ResultCode is ValidationAccepted (0) to accept the payment, non-zero to reject it.
	ResultCode ValidationResultCode `json:"ResultCode" example:"0"`
	// ResultDesc is a short human-readable reason, echoed back to Safaricom.
	ResultDesc string `json:"ResultDesc" example:"Accepted"`

	// ThirdPartyTransID is echoed back on the matching confirmation, which is
	// the only way to correlate the two callbacks.
	ThirdPartyTransID string `json:"ThirdPartyTransID,omitempty"`
}

type ValidationResultCode string

type WrappedAmount struct {
	CurrencyCode string
	Minor        int64
}