{"openapi":"3.1.0","info":{"title":"Pitisha API","version":"2026-10-28","description":"One integration for every way Kenyans pay, and one record of every shilling, in and out. Amounts are integers in the smallest unit (250000 is KES 2,500.00). Money goes straight into your own till."},"servers":[{"url":"{baseUrl}","description":"Your sandbox or live base URL from the portal","variables":{"baseUrl":{"default":"https://YOUR-BASE-URL"}}}],"security":[{"bearer":[]}],"tags":[{"name":"Collections","description":"Take a payment from any source. The customer pays, Pitisha records it and matches it to the sale."},{"name":"Payouts","description":"Send money to a phone or a bank account from a wallet."},{"name":"Settlements","description":"Where your day's money landed, and one record you can export."},{"name":"Wallets","description":"Where your money sits. Assign shortcodes to a wallet and payments to them land there."},{"name":"Shortcodes","description":"Your paybills and tills. View them, configure them and assign them to wallets."},{"name":"Webhook endpoints","description":"Tell Pitisha where to send events, and look back at what was sent."},{"name":"Payment requests","description":"Ask a customer to pay, or give them a link or QR code to pay with."},{"name":"Bulk payouts","description":"Send many payments at once. One approval covers the whole batch."},{"name":"Statements and fees","description":"Every settled movement of money as lines, and the fees we charged."},{"name":"Sandbox tools","description":"Simulate customers paying so you can test your integration end to end. Sandbox keys only."}],"paths":{"/v1/collections":{"post":{"operationId":"create_collection","tags":["Collections"],"summary":"Create a collection","description":"Ask a customer to pay and record the result.\n\nFor till, paybill and QR sources this sends a payment request to the customer's phone. Pitisha routes it through a healthy gateway and, if that gateway fails, moves it to the next one without you retrying. The response is pending until the customer approves; you learn the outcome from the collection.recorded or collection.failed webhook.","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value per logical request, up to 255 characters. Retrying with the same key returns the original result instead of creating a second one.","schema":{"type":"string"}},{"name":"Pitisha-Sandbox-Scenario","in":"header","description":"Sandbox only. Force an outcome: success, insufficient_funds, customer_cancelled or no_response.","schema":{"type":"string"}}],"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"col_8f3k2q","object":"collection","status":"pending","amount":250000,"currency":"KES","source":"paybill","reference":"INV-204117","description":"Order 1042","customer":{"phone":"+254712000000"},"wallet_id":"wal_main","shortcode_id":"sc_4012345","match":null,"routing":{"gateway":"daraja","attempts":1,"failed_over":false},"failure":null,"metadata":{"order_id":"1042"},"livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}}}},"400":{"description":"A parameter is missing or the wrong shape.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was used with different parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The wallet is frozen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","currency","source","customer"],"properties":{"amount":{"type":"integer","description":"Amount in the smallest unit."},"currency":{"type":"string","description":"Always KES.","enum":["KES"]},"source":{"type":"string","description":"How the customer pays.","enum":["till","paybill","qr","bank","airtel"]},"customer":{"type":"object","description":"For mobile money, { phone } in international format."},"shortcode_id":{"type":"string","description":"Which shortcode to collect on. Defaults to your primary one for the source."},"reference":{"type":"string","description":"Your reference. Shown to the customer on a paybill."},"description":{"type":"string","description":"Shown in your portal."},"metadata":{"type":"object","description":"Your own key-value pairs."}}},"example":{"amount":250000,"currency":"KES","source":"paybill","customer":{"phone":"+254712000000"},"reference":"INV-204117","description":"Order 1042","metadata":{"order_id":"1042"}}}}}},"get":{"operationId":"list_collections","tags":["Collections"],"summary":"List collections","description":"Newest first, with filters.","parameters":[{"name":"status","in":"query","description":"Filter by status.","schema":{"type":"string","enum":["pending","succeeded","failed","reversed"]}},{"name":"source","in":"query","description":"Filter by source.","schema":{"type":"string","enum":["till","paybill","qr","bank","airtel"]}},{"name":"match_state","in":"query","description":"Filter by how it matched.","schema":{"type":"string","enum":["matched","pile","no_match"]}},{"name":"wallet_id","in":"query","description":"Only payments into this wallet.","schema":{"type":"string"}},{"name":"created_gte","in":"query","description":"ISO 8601. Created on or after.","schema":{"type":"string"}},{"name":"created_lte","in":"query","description":"ISO 8601. Created on or before.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"How many items to return, from 1 to 100. Defaults to 20.","schema":{"type":"integer"}},{"name":"starting_after","in":"query","description":"A cursor from a previous response's next_cursor. Returns the next page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","data":[{"id":"col_8f3k2q","object":"collection","status":"succeeded","amount":250000,"currency":"KES","source":"paybill","reference":"INV-204117","description":"Order 1042","customer":{"phone":"+254712000000"},"wallet_id":"wal_main","shortcode_id":"sc_4012345","match":{"state":"matched","sale_id":"sale_1042"},"routing":{"gateway":"daraja","attempts":2,"failed_over":true},"failure":null,"metadata":{"order_id":"1042"},"livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}],"has_more":true,"next_cursor":"cur_9fK2mQ"}}}},"400":{"description":"A parameter is missing or the wrong shape.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/collections/{id}":{"get":{"operationId":"retrieve_collection","tags":["Collections"],"summary":"Retrieve a collection","description":"Fetch one collection by id.","parameters":[{"name":"id","in":"path","required":true,"description":"The collection id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"col_8f3k2q","object":"collection","status":"succeeded","amount":250000,"currency":"KES","source":"paybill","reference":"INV-204117","description":"Order 1042","customer":{"phone":"+254712000000"},"wallet_id":"wal_main","shortcode_id":"sc_4012345","match":{"state":"matched","sale_id":"sale_1042"},"routing":{"gateway":"daraja","attempts":2,"failed_over":true},"failure":null,"metadata":{"order_id":"1042"},"livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}}}},"401":{"description":"The API key is missing, wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The object does not exist in this mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/collections/{id}/match":{"post":{"operationId":"resolve_match","tags":["Collections"],"summary":"Resolve a payment in the pile","description":"Choose which sale a pile payment belongs to.\n\nA collection lands in the pile when more than one sale could fit it. Send the sale it belongs to and it becomes matched. A collection with no match can be matched the same way once you find the sale.","parameters":[{"name":"id","in":"path","required":true,"description":"The collection id.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"A unique value per logical request, up to 255 characters. Retrying with the same key returns the original result instead of creating a second one.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"col_8f3k2q","object":"collection","status":"succeeded","amount":250000,"currency":"KES","source":"paybill","reference":"INV-204117","description":"Order 1042","customer":{"phone":"+254712000000"},"wallet_id":"wal_main","shortcode_id":"sc_4012345","match":{"state":"matched","sale_id":"sale_1042"},"routing":{"gateway":"daraja","attempts":2,"failed_over":true},"failure":null,"metadata":{"order_id":"1042"},"livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}}}},"400":{"description":"A parameter is missing or the wrong shape.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The object does not exist in this mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was used with different parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sale_id"],"properties":{"sale_id":{"type":"string","description":"The sale this payment paid for."}}},"example":{"sale_id":"sale_1042"}}}}}},"/v1/payouts":{"post":{"operationId":"create_payout","tags":["Payouts"],"summary":"Create a payout","description":"Send money from a wallet.\n\nThe wallet must hold enough balance for the amount plus the fee. That money is held from the moment you create the payout. If the amount is above your approval threshold the payout starts as pending_approval and is only sent once a different person approves it in the portal (see the Approvals guide). Use an Idempotency-Key so a retry after a network error cannot pay twice.","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value per logical request, up to 255 characters. Retrying with the same key returns the original result instead of creating a second one.","schema":{"type":"string"}}],"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"pay_2xk9d7","object":"payout","status":"pending","amount":1200000,"currency":"KES","destination":{"type":"phone","phone":"+254722000000"},"wallet_id":"wal_payroll","reference":"SALARY-OCT-0007","reason":"salary","fee":2000,"approval":null,"failure":null,"metadata":{},"livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}}}},"400":{"description":"A parameter is missing or the wrong shape.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was used with different parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The business is not fully verified, so payouts are still off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Pitisha has paused this transaction type for everyone, for example payouts to businesses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","currency","wallet_id","destination"],"properties":{"amount":{"type":"integer","description":"Amount in the smallest unit."},"currency":{"type":"string","description":"Always KES.","enum":["KES"]},"wallet_id":{"type":"string","description":"The wallet to pay from."},"destination":{"type":"object","description":"{ type: \"phone\", phone } or { type: \"bank_account\", account_number, bank_code }."},"reference":{"type":"string","description":"Your reference."},"reason":{"type":"string","description":"For example salary, refund or supplier."}}},"example":{"amount":1200000,"currency":"KES","wallet_id":"wal_payroll","destination":{"type":"phone","phone":"+254722000000"},"reference":"SALARY-OCT-0007","reason":"salary"}}}}},"get":{"operationId":"list_payouts","tags":["Payouts"],"summary":"List payouts","description":"Newest first.","parameters":[{"name":"status","in":"query","description":"Filter by status.","schema":{"type":"string","enum":["pending_approval","pending","sent","failed","canceled","rejected"]}},{"name":"wallet_id","in":"query","description":"Only payouts from this wallet.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"How many items to return, from 1 to 100. Defaults to 20.","schema":{"type":"integer"}},{"name":"starting_after","in":"query","description":"A cursor from a previous response's next_cursor. Returns the next page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","data":[{"id":"pay_2xk9d7","object":"payout","status":"sent","amount":1200000,"currency":"KES","destination":{"type":"phone","phone":"+254722000000"},"wallet_id":"wal_payroll","reference":"SALARY-OCT-0007","reason":"salary","fee":2000,"approval":null,"failure":null,"metadata":{},"livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}],"has_more":true,"next_cursor":"cur_9fK2mQ"}}}},"401":{"description":"The API key is missing, wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payouts/{id}":{"get":{"operationId":"retrieve_payout","tags":["Payouts"],"summary":"Retrieve a payout","description":"Fetch one payout by id.","parameters":[{"name":"id","in":"path","required":true,"description":"The payout id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"pay_2xk9d7","object":"payout","status":"sent","amount":1200000,"currency":"KES","destination":{"type":"phone","phone":"+254722000000"},"wallet_id":"wal_payroll","reference":"SALARY-OCT-0007","reason":"salary","fee":2000,"approval":null,"failure":null,"metadata":{},"livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}}}},"404":{"description":"The object does not exist in this mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payouts/{id}/cancel":{"post":{"operationId":"cancel_payout","tags":["Payouts"],"summary":"Cancel a payout","description":"Stop a payout that has not been sent.\n\nOnly a payout that is still pending or waiting for approval can be canceled. Held money returns to the wallet. Once it is sent it cannot be recalled.","parameters":[{"name":"id","in":"path","required":true,"description":"The payout id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"pay_2xk9d7","object":"payout","status":"canceled","amount":1200000,"currency":"KES","destination":{"type":"phone","phone":"+254722000000"},"wallet_id":"wal_payroll","reference":"SALARY-OCT-0007","reason":"salary","fee":2000,"approval":null,"failure":null,"metadata":{},"livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}}}},"400":{"description":"A parameter is missing or the wrong shape.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The object does not exist in this mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/settlements":{"get":{"operationId":"list_settlements","tags":["Settlements"],"summary":"List settlements","description":"Newest first.","parameters":[{"name":"wallet_id","in":"query","description":"Only this wallet.","schema":{"type":"string"}},{"name":"day","in":"query","description":"A trading day, YYYY-MM-DD.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"How many items to return, from 1 to 100. Defaults to 20.","schema":{"type":"integer"}},{"name":"starting_after","in":"query","description":"A cursor from a previous response's next_cursor. Returns the next page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","data":[{"id":"set_5m2c8v","object":"settlement","status":"landed","amount":48250000,"currency":"KES","wallet_id":"wal_main","destination":{"type":"bank_account","account_last4":"2291","bank_code":"01"},"day":"2026-10-27","collections":412,"receipt_url":"https://portal.example.com/receipts/set_5m2c8v","livemode":false,"created_at":"2026-10-28T06:00:00+03:00"}],"has_more":true,"next_cursor":"cur_9fK2mQ"}}}},"401":{"description":"The API key is missing, wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/settlements/{id}":{"get":{"operationId":"retrieve_settlement","tags":["Settlements"],"summary":"Retrieve a settlement","description":"Fetch one settlement.","parameters":[{"name":"id","in":"path","required":true,"description":"The settlement id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"set_5m2c8v","object":"settlement","status":"landed","amount":48250000,"currency":"KES","wallet_id":"wal_main","destination":{"type":"bank_account","account_last4":"2291","bank_code":"01"},"day":"2026-10-27","collections":412,"receipt_url":"https://portal.example.com/receipts/set_5m2c8v","livemode":false,"created_at":"2026-10-28T06:00:00+03:00"}}}},"404":{"description":"The object does not exist in this mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/day-closes/{day}":{"get":{"operationId":"retrieve_day_close","tags":["Settlements"],"summary":"Retrieve a day close","description":"One record for a whole trading day.\n\nTotals for the day, how many payments matched, how many are in the pile and how many have no match, and a link to export the record as CSV for your accountant.","parameters":[{"name":"day","in":"path","required":true,"description":"The trading day, YYYY-MM-DD.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"day_close","day":"2026-10-27","collected":48250000,"paid_out":12000000,"fees":579000,"matched":398,"pile":9,"no_match":5,"export_url":"https://portal.example.com/exports/2026-10-27.csv","livemode":false}}}},"404":{"description":"The object does not exist in this mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/wallets":{"post":{"operationId":"create_wallet","tags":["Wallets"],"summary":"Create a wallet","description":"Add a wallet.","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value per logical request, up to 255 characters. Retrying with the same key returns the original result instead of creating a second one.","schema":{"type":"string"}}],"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"wal_main","object":"wallet","name":"Online shop","currency":"KES","balance":0,"pending":0,"held":0,"status":"active","frozen":false,"shortcode_ids":[],"livemode":false,"created_at":"2026-06-12T09:00:00+03:00"}}}},"400":{"description":"A parameter is missing or the wrong shape.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your key or role cannot do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"A name you choose."},"currency":{"type":"string","description":"Always KES.","enum":["KES"]}}},"example":{"name":"Online shop","currency":"KES"}}}}},"get":{"operationId":"list_wallets","tags":["Wallets"],"summary":"List wallets","description":"All wallets in this mode.","parameters":[{"name":"limit","in":"query","description":"How many items to return, from 1 to 100. Defaults to 20.","schema":{"type":"integer"}},{"name":"starting_after","in":"query","description":"A cursor from a previous response's next_cursor. Returns the next page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","data":[{"id":"wal_main","object":"wallet","name":"Main collections","currency":"KES","balance":128450000,"pending":4230000,"held":0,"status":"active","frozen":false,"shortcode_ids":["sc_4012345","sc_5567890"],"livemode":false,"created_at":"2026-06-12T09:00:00+03:00"}],"has_more":true,"next_cursor":"cur_9fK2mQ"}}}},"401":{"description":"The API key is missing, wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/wallets/{id}":{"get":{"operationId":"retrieve_wallet","tags":["Wallets"],"summary":"Retrieve a wallet","description":"Fetch one wallet and its balance.","parameters":[{"name":"id","in":"path","required":true,"description":"The wallet id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"wal_main","object":"wallet","name":"Main collections","currency":"KES","balance":128450000,"pending":4230000,"held":0,"status":"active","frozen":false,"shortcode_ids":["sc_4012345","sc_5567890"],"livemode":false,"created_at":"2026-06-12T09:00:00+03:00"}}}},"404":{"description":"The object does not exist in this mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"update_wallet","tags":["Wallets"],"summary":"Update a wallet","description":"Rename or freeze a wallet.","parameters":[{"name":"id","in":"path","required":true,"description":"The wallet id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"wal_main","object":"wallet","name":"Main collections","currency":"KES","balance":128450000,"pending":4230000,"held":0,"status":"active","frozen":true,"shortcode_ids":["sc_4012345","sc_5567890"],"livemode":false,"created_at":"2026-06-12T09:00:00+03:00"}}}},"403":{"description":"Your key or role cannot do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The object does not exist in this mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"name":{"type":"string","description":"A new name."},"frozen":{"type":"boolean","description":"Freeze or unfreeze."}}},"example":{"frozen":true}}}}}},"/v1/shortcodes":{"get":{"operationId":"list_shortcodes","tags":["Shortcodes"],"summary":"List shortcodes","description":"All shortcodes in this mode.","parameters":[{"name":"wallet_id","in":"query","description":"Only shortcodes on this wallet.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"How many items to return, from 1 to 100. Defaults to 20.","schema":{"type":"integer"}},{"name":"starting_after","in":"query","description":"A cursor from a previous response's next_cursor. Returns the next page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","data":[{"id":"sc_4012345","object":"shortcode","type":"paybill","number":"4012345","name":"Main paybill","status":"active","wallet_id":"wal_main","callback_url":"https://api.example.com/pitisha/callback","validation":true,"account_format":"Invoice number, 6 digits","livemode":false,"created_at":"2026-06-12T09:30:00+03:00"}],"has_more":true,"next_cursor":"cur_9fK2mQ"}}}},"401":{"description":"The API key is missing, wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/shortcodes/{id}":{"get":{"operationId":"retrieve_shortcode","tags":["Shortcodes"],"summary":"Retrieve a shortcode","description":"Fetch one shortcode.","parameters":[{"name":"id","in":"path","required":true,"description":"The shortcode id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"sc_4012345","object":"shortcode","type":"paybill","number":"4012345","name":"Main paybill","status":"active","wallet_id":"wal_main","callback_url":"https://api.example.com/pitisha/callback","validation":true,"account_format":"Invoice number, 6 digits","livemode":false,"created_at":"2026-06-12T09:30:00+03:00"}}}},"404":{"description":"The object does not exist in this mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"update_shortcode","tags":["Shortcodes"],"summary":"Configure a shortcode","description":"Assign it to a wallet and set how it validates.\n\nSetting wallet_id is how you assign a shortcode to a wallet. From then on, every payment to it lands there.","parameters":[{"name":"id","in":"path","required":true,"description":"The shortcode id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"sc_4012345","object":"shortcode","type":"paybill","number":"4012345","name":"Main paybill","status":"active","wallet_id":"wal_shop","callback_url":"https://api.example.com/pitisha/callback","validation":true,"account_format":"Invoice number, 6 digits","livemode":false,"created_at":"2026-06-12T09:30:00+03:00"}}}},"400":{"description":"A parameter is missing or the wrong shape.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your key or role cannot do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The object does not exist in this mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"wallet_id":{"type":"string","nullable":true,"description":"The wallet to settle to, or null to unassign."},"name":{"type":"string","description":"A new name."},"callback_url":{"type":"string","description":"A new callback URL."},"validation":{"type":"boolean","description":"Paybills only."},"account_format":{"type":"string","description":"The account number rule."}}},"example":{"wallet_id":"wal_shop","validation":true}}}}}},"/v1/webhook_endpoints":{"post":{"operationId":"create_webhook_endpoint","tags":["Webhook endpoints"],"summary":"Create a webhook endpoint","description":"Start receiving events.\n\nThe response includes a secret field with the full signing secret. It is shown once. Store it on your server.","parameters":[],"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"we_71c2xk","object":"webhook_endpoint","url":"https://api.example.com/pitisha/webhooks","events":["collection.recorded","collection.failed","payout.sent","settlement.landed"],"status":"enabled","secret_last4":"71c2","livemode":false,"created_at":"2026-06-12T10:00:00+03:00","secret":"whsec_REPLACE_WITH_REAL_SECRET"}}}},"400":{"description":"A parameter is missing or the wrong shape.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your key or role cannot do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"An HTTPS URL."},"events":{"type":"array","items":{"type":"string"},"description":"Event types to send. Defaults to all."}}},"example":{"url":"https://api.example.com/pitisha/webhooks","events":["collection.recorded","collection.failed"]}}}}},"get":{"operationId":"list_webhook_endpoints","tags":["Webhook endpoints"],"summary":"List webhook endpoints","description":"All endpoints in this mode.","parameters":[{"name":"limit","in":"query","description":"How many items to return, from 1 to 100. Defaults to 20.","schema":{"type":"integer"}},{"name":"starting_after","in":"query","description":"A cursor from a previous response's next_cursor. Returns the next page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","data":[{"id":"we_71c2xk","object":"webhook_endpoint","url":"https://api.example.com/pitisha/webhooks","events":["collection.recorded","collection.failed","payout.sent","settlement.landed"],"status":"enabled","secret_last4":"71c2","livemode":false,"created_at":"2026-06-12T10:00:00+03:00"}],"has_more":true,"next_cursor":"cur_9fK2mQ"}}}},"401":{"description":"The API key is missing, wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook_endpoints/{id}":{"delete":{"operationId":"delete_webhook_endpoint","tags":["Webhook endpoints"],"summary":"Delete a webhook endpoint","description":"Stop sending to it.","parameters":[{"name":"id","in":"path","required":true,"description":"The endpoint id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"we_71c2xk","object":"webhook_endpoint","deleted":true}}}},"404":{"description":"The object does not exist in this mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/events":{"get":{"operationId":"list_events","tags":["Webhook endpoints"],"summary":"List events","description":"Everything Pitisha has sent you.","parameters":[{"name":"type","in":"query","description":"Filter by event type.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"How many items to return, from 1 to 100. Defaults to 20.","schema":{"type":"integer"}},{"name":"starting_after","in":"query","description":"A cursor from a previous response's next_cursor. Returns the next page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","data":[{"id":"evt_6h2p0q","object":"event","type":"collection.recorded","created_at":"2026-10-28T11:20:04+03:00","livemode":false,"data":{"object":{"id":"col_8f3k2q","object":"collection","status":"succeeded","amount":250000,"currency":"KES","source":"paybill","reference":"INV-204117","description":"Order 1042","customer":{"phone":"+254712000000"},"wallet_id":"wal_main","shortcode_id":"sc_4012345","match":{"state":"matched","sale_id":"sale_1042"},"routing":{"gateway":"daraja","attempts":2,"failed_over":true},"failure":null,"metadata":{"order_id":"1042"},"livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}}}],"has_more":true,"next_cursor":"cur_9fK2mQ"}}}},"401":{"description":"The API key is missing, wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/events/{id}/redeliver":{"post":{"operationId":"redeliver_event","tags":["Webhook endpoints"],"summary":"Redeliver an event","description":"Send an event to your endpoint again.\n\nUseful after you fix an outage on your side. The same event id is sent, so make your handler idempotent.","parameters":[{"name":"id","in":"path","required":true,"description":"The event id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"evt_6h2p0q","object":"event","type":"collection.recorded","created_at":"2026-10-28T11:20:04+03:00","livemode":false,"data":{"object":{"id":"col_8f3k2q","object":"collection","status":"succeeded","amount":250000,"currency":"KES","source":"paybill","reference":"INV-204117","description":"Order 1042","customer":{"phone":"+254712000000"},"wallet_id":"wal_main","shortcode_id":"sc_4012345","match":{"state":"matched","sale_id":"sale_1042"},"routing":{"gateway":"daraja","attempts":2,"failed_over":true},"failure":null,"metadata":{"order_id":"1042"},"livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}}}}}},"404":{"description":"The object does not exist in this mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payment_requests":{"post":{"operationId":"create_payment_request","tags":["Payment requests"],"summary":"Request a payment","description":"Send a prompt to a customer's phone.\n\nThe customer gets an M-Pesa prompt for the amount. You get collection.recorded when they pay, or collection.failed if they decline or time out.","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value per logical request, up to 255 characters. Retrying with the same key returns the original result instead of creating a second one.","schema":{"type":"string"}}],"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"pr_4n7c2x","object":"payment_request","status":"sent","amount":250000,"currency":"KES","wallet_id":"wal_main","customer":{"phone":"+254712000000"},"livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}}}},"400":{"description":"A parameter is missing or the wrong shape.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was used with different parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The wallet is frozen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Pitisha has paused this transaction type for everyone, for example payouts to businesses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","wallet_id","customer"],"properties":{"amount":{"type":"integer","description":"Amount in the smallest unit."},"wallet_id":{"type":"string","description":"The wallet the money should land in."},"customer":{"type":"object","description":"{ phone }."},"description":{"type":"string","description":"Shown to the customer where the network allows."}}},"example":{"amount":250000,"wallet_id":"wal_main","customer":{"phone":"+254712000000"},"description":"Order 1042"}}}}}},"/v1/payment_links":{"post":{"operationId":"create_payment_link","tags":["Payment requests"],"summary":"Create a payment link","description":"A shareable page that takes payment.\n\nLeave amount out to let the payer choose. Disable the link with PATCH when you no longer want it used.","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value per logical request, up to 255 characters. Retrying with the same key returns the original result instead of creating a second one.","schema":{"type":"string"}}],"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"pl_9k2m4d","object":"payment_link","title":"School fees, Term 3","amount":null,"wallet_id":"wal_main","url":"https://pay.example.com/l/9k2m4d","active":true,"livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}}}},"400":{"description":"A parameter is missing or the wrong shape.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was used with different parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","wallet_id"],"properties":{"title":{"type":"string","description":"What the payer sees."},"amount":{"type":"integer","nullable":true,"description":"A fixed amount, or null for any amount."},"wallet_id":{"type":"string","description":"Where the money lands."}}},"example":{"title":"School fees, Term 3","amount":null,"wallet_id":"wal_main"}}}}}},"/v1/payout_batches":{"post":{"operationId":"create_payout_batch","tags":["Bulk payouts"],"summary":"Create a bulk payout","description":"Submit a list of payouts.\n\nRows that fail validation are rejected with the row number and nothing is held. A valid batch is held and waits for approval. Each row becomes a normal payout, so you also get payout.sent or payout.failed for every row.","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value per logical request, up to 255 characters. Retrying with the same key returns the original result instead of creating a second one.","schema":{"type":"string"}}],"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"pb_3d8w1q","object":"payout_batch","status":"pending_approval","total":2150000,"counts":{"rows":2,"sent":0,"failed":0},"wallet_id":"wal_payroll","livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}}}},"400":{"description":"A parameter is missing or the wrong shape.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was used with different parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The business is not fully verified, so payouts are still off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["wallet_id","rows"],"properties":{"wallet_id":{"type":"string","description":"The wallet to pay from."},"name":{"type":"string","description":"A label for your own records."},"rows":{"type":"string","description":"Each row: { amount, destination, reference }."}}},"example":{"wallet_id":"wal_payroll","name":"October salaries","rows":[{"amount":1200000,"destination":{"type":"phone","phone":"+254722000000"},"reference":"SAL-0001"},{"amount":950000,"destination":{"type":"phone","phone":"+254733000000"},"reference":"SAL-0002"}]}}}}}},"/v1/payout_batches/{id}":{"get":{"operationId":"retrieve_payout_batch","tags":["Bulk payouts"],"summary":"Retrieve a bulk payout","description":"Progress and counts.","parameters":[{"name":"id","in":"path","required":true,"description":"The batch id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"pb_3d8w1q","object":"payout_batch","status":"sending","total":2150000,"counts":{"rows":2,"sent":1,"failed":0},"wallet_id":"wal_payroll","livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}}}},"404":{"description":"The object does not exist in this mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/statement":{"get":{"operationId":"list_statement_lines","tags":["Statements and fees"],"summary":"List statement lines","description":"Newest first, filtered on the server.","parameters":[{"name":"wallet_id","in":"query","description":"Only this wallet.","schema":{"type":"string"}},{"name":"kind","in":"query","description":"Only this kind of line.","schema":{"type":"string","enum":["collection","payout","settlement","fee","adjustment"]}},{"name":"from","in":"query","description":"Start date, YYYY-MM-DD.","schema":{"type":"string"}},{"name":"to","in":"query","description":"End date, YYYY-MM-DD.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"How many items to return, from 1 to 100. Defaults to 20.","schema":{"type":"integer"}},{"name":"starting_after","in":"query","description":"A cursor from a previous response's next_cursor. Returns the next page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","data":[{"id":"ln_7b2k9x","object":"statement_line","kind":"fee","amount":-250,"wallet_id":"wal_main","reference":"PTS-8F3K2Q","description":"Collection fee","livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}],"has_more":true,"next_cursor":"cur_9fK2mQ"}}}},"400":{"description":"A parameter is missing or the wrong shape.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/fees":{"get":{"operationId":"list_fees","tags":["Statements and fees"],"summary":"List fees","description":"Only the fee lines.\n\nThe same as the statement filtered to kind=fee, so you can reconcile what you were charged against your own records.","parameters":[{"name":"wallet_id","in":"query","description":"Only this wallet.","schema":{"type":"string"}},{"name":"from","in":"query","description":"Start date, YYYY-MM-DD.","schema":{"type":"string"}},{"name":"to","in":"query","description":"End date, YYYY-MM-DD.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"How many items to return, from 1 to 100. Defaults to 20.","schema":{"type":"integer"}},{"name":"starting_after","in":"query","description":"A cursor from a previous response's next_cursor. Returns the next page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","data":[{"id":"ln_7b2k9x","object":"statement_line","kind":"fee","amount":-250,"wallet_id":"wal_main","reference":"PTS-8F3K2Q","description":"Collection fee","livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}],"has_more":true,"next_cursor":"cur_9fK2mQ"}}}},"401":{"description":"The API key is missing, wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/collections/{id}/query":{"post":{"operationId":"query_collection_status","tags":["Statements and fees"],"summary":"Check a pending collection","description":"Ask the network what happened.\n\nUse it on a collection that has been pending longer than expected. We ask the provider and update the collection. Never create a second collection to retry.","parameters":[{"name":"id","in":"path","required":true,"description":"The collection id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"col_8f3k2q","object":"collection","status":"succeeded","amount":250000,"currency":"KES","source":"paybill","reference":"INV-204117","description":"Order 1042","customer":{"phone":"+254712000000"},"wallet_id":"wal_main","shortcode_id":"sc_4012345","match":{"state":"matched","sale_id":"sale_1042"},"routing":{"gateway":"daraja","attempts":2,"failed_over":true},"failure":null,"metadata":{"order_id":"1042"},"livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}}}},"404":{"description":"The object does not exist in this mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sandbox/shortcodes/{id}/simulate_payment":{"post":{"operationId":"simulate_payment","tags":["Sandbox tools"],"summary":"Simulate a customer paying","description":"Pay one of your sandbox shortcodes as a customer.\n\nCreates a collection as if a customer had paid your sandbox paybill or till, then sends the webhooks. Use scenario to test failures.","parameters":[{"name":"id","in":"path","required":true,"description":"A sandbox shortcode id.","schema":{"type":"string"}}],"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"col_8f3k2q","object":"collection","status":"succeeded","amount":250000,"currency":"KES","source":"paybill","reference":"INV-204117","description":"Order 1042","customer":{"phone":"+254712000000"},"wallet_id":"wal_main","shortcode_id":"sc_4012345","match":{"state":"matched","sale_id":"sale_1042"},"routing":{"gateway":"daraja","attempts":2,"failed_over":true},"failure":null,"metadata":{"order_id":"1042"},"livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}}}},"400":{"description":"A parameter is missing or the wrong shape.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your key or role cannot do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The object does not exist in this mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"integer","description":"Amount in the smallest unit."},"reference":{"type":"string","description":"The account number the customer types on a paybill."},"scenario":{"type":"string","description":"The outcome to simulate.","enum":["success","insufficient_funds","customer_cancelled","no_response"]}}},"example":{"amount":150000,"reference":"INV-204117","scenario":"success"}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Send your secret key: Authorization: Bearer sk_test_..."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","authentication_failed","permission_denied","not_found","idempotency_conflict","insufficient_funds","wallet_frozen","shortcode_inactive","verification_required","service_stopped","rate_limited","api_error"]},"message":{"type":"string"},"param":{"type":"string"},"request_id":{"type":"string"}}}}},"Collection":{"type":"object","required":[],"properties":{"id":{"type":"string","description":"Unique identifier, starting col_."},"status":{"type":"string","description":"Where the payment is.","enum":["pending","succeeded","failed","reversed"]},"amount":{"type":"integer","description":"Amount in the smallest unit. 250000 is KES 2,500.00."},"currency":{"type":"string","description":"Always KES."},"source":{"type":"string","description":"How the customer paid.","enum":["till","paybill","qr","bank","airtel"]},"reference":{"type":"string","nullable":true,"description":"Your reference, for example an invoice or account number."},"customer":{"type":"object","description":"Who paid: a phone number for mobile money, or account details for bank transfers."},"wallet_id":{"type":"string","description":"The wallet the payment landed in."},"shortcode_id":{"type":"string","nullable":true,"description":"The paybill or till it was paid to."},"match":{"type":"object","nullable":true,"description":"How the payment matched your sales. match.state is matched, pile or no_match. See Matching."},"routing":{"type":"object","description":"Which gateway took the payment, how many attempts it needed, and whether the smart switch failed over. See Gateways and failover."},"failure":{"type":"object","nullable":true,"description":"Present when status is failed: a code and a message."},"metadata":{"type":"object","description":"Up to 20 key-value pairs of your own."},"livemode":{"type":"boolean","description":"false in the sandbox."},"created_at":{"type":"string","description":"ISO 8601 timestamp."}},"example":{"id":"col_8f3k2q","object":"collection","status":"succeeded","amount":250000,"currency":"KES","source":"paybill","reference":"INV-204117","description":"Order 1042","customer":{"phone":"+254712000000"},"wallet_id":"wal_main","shortcode_id":"sc_4012345","match":{"state":"matched","sale_id":"sale_1042"},"routing":{"gateway":"daraja","attempts":2,"failed_over":true},"failure":null,"metadata":{"order_id":"1042"},"livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}},"Payout":{"type":"object","required":[],"properties":{"id":{"type":"string","description":"Unique identifier, starting pay_."},"status":{"type":"string","description":"Where the payout is. pending_approval means a second person must approve it first; the money is held meanwhile.","enum":["pending_approval","pending","sent","failed","canceled","rejected"]},"amount":{"type":"integer","description":"Amount in the smallest unit."},"currency":{"type":"string","description":"Always KES."},"destination":{"type":"object","description":"A phone number or a bank account."},"wallet_id":{"type":"string","description":"The wallet the money came from."},"reference":{"type":"string","nullable":true,"description":"Your reference."},"fee":{"type":"integer","description":"The fee charged for this payout, in the smallest unit."},"approval":{"type":"object","nullable":true,"description":"Present when the payout needed approval: { required, requested_by, decided_by, decided_at }."},"failure":{"type":"object","nullable":true,"description":"A code and message when status is failed."},"livemode":{"type":"boolean","description":"false in the sandbox."},"created_at":{"type":"string","description":"ISO 8601 timestamp."}},"example":{"id":"pay_2xk9d7","object":"payout","status":"sent","amount":1200000,"currency":"KES","destination":{"type":"phone","phone":"+254722000000"},"wallet_id":"wal_payroll","reference":"SALARY-OCT-0007","reason":"salary","fee":2000,"approval":null,"failure":null,"metadata":{},"livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}},"Settlement":{"type":"object","required":[],"properties":{"id":{"type":"string","description":"Unique identifier, starting set_."},"status":{"type":"string","description":"Whether the money has landed.","enum":["pending","landed"]},"amount":{"type":"integer","description":"Amount in the smallest unit."},"wallet_id":{"type":"string","description":"The wallet this settlement belongs to."},"destination":{"type":"object","description":"Where it landed."},"day":{"type":"string","description":"The trading day, YYYY-MM-DD."},"collections":{"type":"integer","description":"How many collections it covers."},"receipt_url":{"type":"string","description":"A link to the receipt in your portal."},"created_at":{"type":"string","description":"ISO 8601 timestamp."}},"example":{"id":"set_5m2c8v","object":"settlement","status":"landed","amount":48250000,"currency":"KES","wallet_id":"wal_main","destination":{"type":"bank_account","account_last4":"2291","bank_code":"01"},"day":"2026-10-27","collections":412,"receipt_url":"https://portal.example.com/receipts/set_5m2c8v","livemode":false,"created_at":"2026-10-28T06:00:00+03:00"}},"Wallet":{"type":"object","required":[],"properties":{"id":{"type":"string","description":"Unique identifier, starting wal_."},"name":{"type":"string","description":"A name you choose."},"balance":{"type":"integer","description":"Available balance in the smallest unit."},"pending":{"type":"integer","description":"Pending in, not yet available."},"held":{"type":"integer","description":"Reserved for payouts that are waiting for approval or still being sent. Not available to spend."},"status":{"type":"string","description":"Locked and suspended wallets cannot send payouts. Dormant wallets have had no activity for 90 days.","enum":["active","suspended","locked","dormant"]},"frozen":{"type":"boolean","description":"A frozen wallet takes no payments and sends no payouts."},"shortcode_ids":{"type":"array","items":{"type":"string"},"description":"Shortcodes assigned to this wallet."},"created_at":{"type":"string","description":"ISO 8601 timestamp."}},"example":{"id":"wal_main","object":"wallet","name":"Main collections","currency":"KES","balance":128450000,"pending":4230000,"held":0,"status":"active","frozen":false,"shortcode_ids":["sc_4012345","sc_5567890"],"livemode":false,"created_at":"2026-06-12T09:00:00+03:00"}},"Shortcode":{"type":"object","required":[],"properties":{"id":{"type":"string","description":"Unique identifier, starting sc_."},"type":{"type":"string","description":"Paybill or till.","enum":["paybill","till"]},"number":{"type":"string","description":"The number customers pay."},"name":{"type":"string","description":"A name you choose."},"status":{"type":"string","description":"Whether it takes payments.","enum":["active","pending","suspended"]},"wallet_id":{"type":"string","nullable":true,"description":"The wallet payments to this shortcode land in."},"callback_url":{"type":"string","description":"Where Pitisha sends each payment as a signed webhook."},"validation":{"type":"boolean","description":"Paybills only. Reject payments whose account number does not fit account_format."},"account_format":{"type":"string","description":"The account number rule."}},"example":{"id":"sc_4012345","object":"shortcode","type":"paybill","number":"4012345","name":"Main paybill","status":"active","wallet_id":"wal_main","callback_url":"https://api.example.com/pitisha/callback","validation":true,"account_format":"Invoice number, 6 digits","livemode":false,"created_at":"2026-06-12T09:30:00+03:00"}},"Webhookendpoint":{"type":"object","required":[],"properties":{"id":{"type":"string","description":"Unique identifier, starting we_."},"url":{"type":"string","description":"Your HTTPS endpoint."},"events":{"type":"array","items":{"type":"string"},"description":"Which event types to send."},"status":{"type":"string","description":"Whether events are being sent.","enum":["enabled","disabled"]},"secret_last4":{"type":"string","description":"The last four characters of the signing secret. The full secret is shown once when you create the endpoint."}},"example":{"id":"we_71c2xk","object":"webhook_endpoint","url":"https://api.example.com/pitisha/webhooks","events":["collection.recorded","collection.failed","payout.sent","settlement.landed"],"status":"enabled","secret_last4":"71c2","livemode":false,"created_at":"2026-06-12T10:00:00+03:00"}},"Payoutbatch":{"type":"object","required":[],"properties":{"id":{"type":"string","description":"Unique identifier, starting pb_."},"status":{"type":"string","description":"Where the batch is.","enum":["draft","pending_approval","sending","complete","rejected"]},"total":{"type":"integer","description":"Sum of all rows in the smallest unit."},"counts":{"type":"object","description":"{ rows, sent, failed }."},"wallet_id":{"type":"string","description":"The wallet the money comes from."}},"example":{"id":"pb_3d8w1q","object":"payout_batch","status":"pending_approval","total":5400000,"counts":{"rows":36,"sent":0,"failed":0},"wallet_id":"wal_payroll","livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}},"Statementline":{"type":"object","required":[],"properties":{"id":{"type":"string","description":"Unique identifier, starting ln_."},"kind":{"type":"string","description":"What the line is.","enum":["collection","payout","settlement","fee","adjustment"]},"amount":{"type":"integer","description":"Signed amount in the smallest unit."},"wallet_id":{"type":"string","description":"The wallet affected."},"reference":{"type":"string","description":"Shared by every line from the same transaction."},"description":{"type":"string","description":"Plain-language description."},"created_at":{"type":"string","description":"ISO 8601 timestamp."}},"example":{"id":"ln_7b2k9x","object":"statement_line","kind":"fee","amount":-250,"wallet_id":"wal_main","reference":"PTS-8F3K2Q","description":"Collection fee","livemode":false,"created_at":"2026-10-28T11:20:04+03:00"}}}}}