> For the complete documentation index, see [llms.txt](https://developers.share.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.share.inc/api-reference/payments.md).

# Payments

Subscriber-facing payment surface: look up paybill routing, initiate a push-payment (STK push via SasaPay), and read payment status. The split-execution rail is internal — partners observe splits indirectly through Banking balances and Billing receipts. See the Revenue split concept guide for the end-to-end picture.

## Get paybill details

> Returns the paybill account and routing details a subscriber should use to settle outstanding charges.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Subscriber-facing payment surface: look up paybill routing, initiate a push-payment (STK push via SasaPay), and read payment status. The split-execution rail is internal — partners observe splits indirectly through Banking balances and Billing receipts. See the Revenue split concept guide for the end-to-end picture.","name":"Payments"}],"security":[{"X-Access-Secret":[]},{"X-Access-Id":[]}],"components":{"securitySchemes":{"X-Access-Secret":{"description":"Provider Access Secret Key (JWT)","in":"header","name":"X-Access-Secret","type":"apiKey"},"X-Access-Id":{"description":"Provider Access ID","in":"header","name":"X-Access-Id","type":"apiKey"}},"schemas":{"ApiResponseDto":{"properties":{},"type":"object"},"PaybillResponseDto":{"properties":{"accountReference":{"description":"Account reference for the payment","type":"string"},"balanceAmount":{"description":"Outstanding balance","type":"number"},"balanceCurrency":{"description":"ISO 4217 currency code","type":"string"},"externalUserId":{"description":"User ID in the partner's platform","type":"string"},"id":{"description":"Share internal user ID","format":"uuid","type":"string"},"paybillNumber":{"description":"Paybill number for mobile money payments","type":"string"}},"required":["id","externalUserId","paybillNumber","accountReference","balanceAmount","balanceCurrency"],"type":"object"}}},"paths":{"/v1/payments/{subscriberId}/paybill":{"get":{"description":"Returns the paybill account and routing details a subscriber should use to settle outstanding charges.","operationId":"PaymentsController_getPaybill_v1","parameters":[{"description":"Subscriber identifier (UUID).","in":"path","name":"subscriberId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/PaybillResponseDto"},"success":{"type":"boolean"}}}]}}},"description":"Paybill details for the subscriber."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"rejectionReasons":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"type":"array"},"success":{"type":"boolean"}}}}},"description":"Validation failed"},"401":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Unauthorized — missing or invalid credentials"},"403":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Forbidden — insufficient permissions"},"404":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Resource not found"},"408":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Request timeout"},"500":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Internal server error"}},"summary":"Get paybill details","tags":["Payments"]}}}}
```

## Get subscriber payment status

> Returns the current payment status for a subscriber, including in-flight and recently settled transactions.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Subscriber-facing payment surface: look up paybill routing, initiate a push-payment (STK push via SasaPay), and read payment status. The split-execution rail is internal — partners observe splits indirectly through Banking balances and Billing receipts. See the Revenue split concept guide for the end-to-end picture.","name":"Payments"}],"security":[{"X-Access-Secret":[]},{"X-Access-Id":[]}],"components":{"securitySchemes":{"X-Access-Secret":{"description":"Provider Access Secret Key (JWT)","in":"header","name":"X-Access-Secret","type":"apiKey"},"X-Access-Id":{"description":"Provider Access ID","in":"header","name":"X-Access-Id","type":"apiKey"}},"schemas":{"ApiResponseDto":{"properties":{},"type":"object"},"PaymentStatusResponseDto":{"properties":{"billingCycleEnd":{"description":"End of current billing period","format":"date-time","type":"string"},"daysRemaining":{"description":"Days remaining in current billing cycle","type":"number"},"externalUserId":{"description":"User ID in the partner's platform","type":"string"},"gracePeriodEnd":{"description":"When grace period ends (if applicable)","format":"date-time","type":"object"},"id":{"description":"Share internal user ID","format":"uuid","type":"string"},"nextPaymentDue":{"description":"Next payment due date","format":"date-time","type":"string"},"paymentStatus":{"description":"Current payment status","enum":["active","expired","suspended","grace_period"],"type":"string"}},"required":["id","externalUserId","paymentStatus","billingCycleEnd","nextPaymentDue","daysRemaining"],"type":"object"}}},"paths":{"/v1/payments/{subscriberId}/payment-status":{"get":{"description":"Returns the current payment status for a subscriber, including in-flight and recently settled transactions.","operationId":"PaymentsController_getPaymentStatus_v1","parameters":[{"description":"Subscriber identifier (UUID).","in":"path","name":"subscriberId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/PaymentStatusResponseDto"},"success":{"type":"boolean"}}}]}}},"description":"Current payment status for the subscriber."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"rejectionReasons":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"type":"array"},"success":{"type":"boolean"}}}}},"description":"Validation failed"},"401":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Unauthorized — missing or invalid credentials"},"403":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Forbidden — insufficient permissions"},"404":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Resource not found"},"408":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Request timeout"},"500":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Internal server error"}},"summary":"Get subscriber payment status","tags":["Payments"]}}}}
```

## Initiate a push payment

> Triggers a mobile-money STK push to the subscriber so they can authorize a payment for the configured amount.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Subscriber-facing payment surface: look up paybill routing, initiate a push-payment (STK push via SasaPay), and read payment status. The split-execution rail is internal — partners observe splits indirectly through Banking balances and Billing receipts. See the Revenue split concept guide for the end-to-end picture.","name":"Payments"}],"security":[{"X-Access-Secret":[]},{"X-Access-Id":[]}],"components":{"securitySchemes":{"X-Access-Secret":{"description":"Provider Access Secret Key (JWT)","in":"header","name":"X-Access-Secret","type":"apiKey"},"X-Access-Id":{"description":"Provider Access ID","in":"header","name":"X-Access-Id","type":"apiKey"}},"schemas":{"PushPaymentRequestDto":{"properties":{"packageId":{"description":"Package ID this payment covers","format":"uuid","type":"string"},"paymentAmount":{"description":"Payment amount","type":"number"},"paymentCurrency":{"description":"ISO 4217 currency code","type":"string"},"paymentMethod":{"description":"Payment method used","enum":["mobile_money","card","bank_transfer","cash"],"type":"string"},"thirdPartyPaymentRef":{"description":"Partner's internal payment reference","type":"string"}},"required":["paymentAmount","paymentCurrency","paymentMethod"],"type":"object"},"ApiResponseDto":{"properties":{},"type":"object"},"PushPaymentResponseDto":{"properties":{"billingCycleEnd":{"description":"End of current billing period","format":"date-time","type":"object"},"billingCycleStart":{"description":"Start of current billing period","format":"date-time","type":"object"},"externalUserId":{"description":"User ID in the partner's platform","type":"string"},"gracePeriodEnd":{"description":"When grace period ends (hard cutoff)","format":"date-time","type":"object"},"id":{"description":"Share internal user ID","format":"uuid","type":"string"},"nextPaymentDue":{"description":"Next payment due date","format":"date-time","type":"string"},"packageId":{"description":"Package this payment covers","format":"uuid","type":"object"},"paymentAmount":{"type":"number"},"paymentCurrency":{"description":"ISO 4217 currency code","type":"string"},"paymentEventType":{"description":"Payment event type","enum":["payment_received","payment_failed","payment_expired","refund_issued"],"type":"string"},"paymentMethod":{"description":"Payment method used","enum":["mobile_money","card","bank_transfer","cash"],"type":"string"},"paymentStatus":{"description":"Current payment status","enum":["active","expired","suspended","grace_period"],"type":"string"},"timestamp":{"format":"date-time","type":"string"},"transactionId":{"description":"Share's payment reference","type":"string"}},"required":["transactionId","id","externalUserId","paymentEventType","paymentAmount","paymentCurrency","paymentMethod","paymentStatus","nextPaymentDue","timestamp"],"type":"object"}}},"paths":{"/v1/payments/{subscriberId}/push-payment":{"post":{"description":"Triggers a mobile-money STK push to the subscriber so they can authorize a payment for the configured amount.","operationId":"PaymentsController_pushPayment_v1","parameters":[{"description":"Subscriber identifier (UUID).","in":"path","name":"subscriberId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushPaymentRequestDto"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/PushPaymentResponseDto"},"success":{"type":"boolean"}}}]}}},"description":"Push payment accepted and dispatched."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"rejectionReasons":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"type":"array"},"success":{"type":"boolean"}}}}},"description":"Validation failed"},"401":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Unauthorized — missing or invalid credentials"},"403":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Forbidden — insufficient permissions"},"404":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Resource not found"},"408":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Request timeout"},"500":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Internal server error"}},"summary":"Initiate a push payment","tags":["Payments"]}}}}
```