{"openapi":"3.0.3","info":{"title":"Billy Catalog API","version":"1.0.0","description":"Read-only access to the Billy biller catalog: categories, billers, field schemas, fees and fee quotes.\n\n## Authentication\nEvery endpoint (except this spec and the docs page) requires a partner API key, issued via `billy:issue-api-key` and sent as `Authorization: Bearer <key>`.\n\n## Rate limits\n120 requests\/minute per partner.\n\n## Logos\nA biller's `logo_url` (when present) is an absolute URL served by the platform, e.g. `\/billers\/logos\/PLDT.png`. About a third of billers currently have a logo; the rest are `null`."},"servers":[{"url":"https:\/\/billy.finfactory.dev\/api\/v1","description":"This environment"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Categories","description":"Biller categories."},{"name":"Billers","description":"Billers, field schemas, fees and quotes."},{"name":"Payments","description":"Pay a bill (beta)."},{"name":"Wallet","description":"Your prefunded PHP float (beta)."},{"name":"Top-ups","description":"Fund your PHP float (beta)."},{"name":"Webhooks","description":"Outbound webhook delivery log (beta)."}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","description":"Partner API key issued via `billy:issue-api-key`. Send as `Authorization: Bearer <key>`."}},"schemas":{"Category":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string","example":"Telecommunications"},"slug":{"type":"string","example":"telecommunications"},"billers_count":{"type":"integer","nullable":true,"description":"Count of active billers (present when requested)."}}},"BillerType":{"type":"object","nullable":true,"properties":{"value":{"type":"integer","enum":[1,2,3]},"label":{"type":"string","example":"Offline"},"supports_inquiry":{"type":"boolean","description":"True for Online billers (real-time account inquiry)."}}},"BillerField":{"type":"object","description":"One input field a payer must supply for this biller.","properties":{"position":{"type":"integer","enum":[1,2]},"name":{"type":"string","example":"10 Digit Account Number"},"format":{"type":"string","nullable":true,"enum":["numeric","alphanumeric"]},"width":{"type":"integer","nullable":true,"description":"Maximum length."},"required":{"type":"boolean"},"validation_regex":{"type":"string","nullable":true,"example":"\/^[0-9]{1,10}$\/","description":"Regex to validate input. Alphanumeric fields allow spaces."}}},"BillerFee":{"type":"object","description":"Decimal strings (2 dp).","properties":{"service_fee":{"type":"string","example":"7.00"},"convenience_fee":{"type":"string","example":"0.00"},"merchant_comm":{"type":"string","example":"3.50"},"biller_share":{"type":"string","example":"0.00"},"effective_from":{"type":"string","format":"date"}}},"BillerPolicy":{"type":"object","properties":{"type":{"type":"string","enum":["general","cutoff","acceptance"]},"text":{"type":"string"},"cutoff_time":{"type":"string","nullable":true,"example":"20:00:00"}}},"Biller":{"type":"object","properties":{"id":{"type":"string","description":"Opaque public biller id (ULID) \u2014 use this in \/billers\/{id} and quote requests."},"code":{"type":"string","nullable":true,"description":"Short biller code \/ identifier (the biller's \"short name\"), e.g. \"PLDT\"."},"name":{"type":"string","description":"Full descriptive biller name (the biller's \"long name\")."},"slug":{"type":"string","description":"URL-safe slug derived from the code."},"description":{"type":"string","nullable":true},"logo_url":{"type":"string","nullable":true,"format":"uri","description":"Absolute URL to the full biller logo (\u2264512px), for detail views. Null when none is available."},"logo_thumb_url":{"type":"string","nullable":true,"format":"uri","description":"Absolute URL to the thumbnail logo (\u2264128px), for list views. Null when none is available."},"status":{"type":"string","enum":["active","strict","deactivated"]},"biller_type":{"$ref":"#\/components\/schemas\/BillerType"},"service_type":{"type":"string","nullable":true,"enum":["ecbills","ectickets"]},"area_of_coverage":{"type":"string","nullable":true},"min_amount":{"type":"string","nullable":true,"description":"Minimum payable amount, or null if unbounded."},"max_amount":{"type":"string","nullable":true,"description":"Maximum payable amount, or null if unbounded."},"categories":{"type":"array","items":{"$ref":"#\/components\/schemas\/Category"},"description":"Every category the biller belongs to."},"category":{"allOf":[{"$ref":"#\/components\/schemas\/Category"}],"nullable":true,"deprecated":true,"description":"The first category, for backward compatibility. Prefer `categories`."},"fields":{"type":"array","description":"Included on the detail endpoint.","items":{"$ref":"#\/components\/schemas\/BillerField"}},"current_fee":{"allOf":[{"$ref":"#\/components\/schemas\/BillerFee"}],"nullable":true,"description":"Included on the detail endpoint."},"policies":{"type":"array","description":"Included on the detail endpoint.","items":{"$ref":"#\/components\/schemas\/BillerPolicy"}}}},"BillerSuggestion":{"type":"object","description":"Minimal biller shape for typeahead results.","properties":{"id":{"type":"string","description":"Opaque public biller id (ULID)."},"code":{"type":"string","nullable":true},"name":{"type":"string"},"logo_thumb_url":{"type":"string","nullable":true,"format":"uri"}}},"BillerCollection":{"type":"object","description":"Laravel-style paginated collection of billers.","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Biller"}},"links":{"type":"object","properties":{"first":{"type":"string","nullable":true},"last":{"type":"string","nullable":true},"prev":{"type":"string","nullable":true},"next":{"type":"string","nullable":true}}},"meta":{"type":"object","properties":{"current_page":{"type":"integer"},"from":{"type":"integer","nullable":true},"last_page":{"type":"integer"},"path":{"type":"string"},"per_page":{"type":"integer"},"to":{"type":"integer","nullable":true},"total":{"type":"integer"}}}}},"Quote":{"type":"object","properties":{"biller":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string","nullable":true},"name":{"type":"string"}}},"funding_source":{"type":"string","enum":["wallet","collect"],"description":"Echoes the quoted funding source (default `wallet`)."},"amount":{"type":"string","example":"1500.00"},"convenience_fee":{"type":"string","example":"20.00","description":"The provider's convenience fee, charged on top of the bill."},"platform_fee":{"type":"string","example":"25.00","description":"Billy's fee for the posting."},"gateway_fee":{"type":"string","example":"0.00","description":"The payment gateway's processing fee, surcharged to the payer on `collect`. Always `0.00` on `wallet`."},"customer_total":{"type":"string","example":"1545.00","description":"What the payer owes: amount + convenience_fee + platform_fee + gateway_fee. Higher on `collect` by the gateway_fee."},"fee_breakdown":{"$ref":"#\/components\/schemas\/BillerFeeBreakdown"},"currency":{"type":"string","example":"PHP"}}},"BillerFeeBreakdown":{"type":"object","description":"The provider's own economics for this biller, for transparency. Does not affect what you are charged.","properties":{"service_fee":{"type":"string","description":"The provider MDR, taken out of the bill (the biller receives less)."},"convenience_fee":{"type":"string"},"provider_pool":{"type":"string","description":"service_fee + convenience_fee."},"ff_revenue_share":{"type":"string","description":"Billy's commission from the pool."}}},"PaymentRequest":{"type":"object","description":"Beta. Body for creating a payment.","required":["amount","fields"],"properties":{"amount":{"type":"number","format":"float","example":1500,"description":"Amount to pay, > 0 and within the biller min\/max when set."},"fields":{"type":"object","description":"Biller input fields, keyed by position (`field_1`, `field_2`, \u2026) and validated against the biller field schema.","additionalProperties":{"type":"string"},"example":{"field_1":"1234567890"}},"external_customer_ref":{"type":"string","nullable":true,"description":"Opaque, app-supplied reference for your end-user. Stored with the payment."},"metadata":{"type":"object","nullable":true,"description":"Arbitrary key\/value passthrough, echoed on the payment and webhooks.","additionalProperties":{"type":"string"}},"funding_source":{"type":"string","nullable":true,"enum":["wallet","collect"],"description":"Default `wallet` (debit your float). `collect` returns a `checkout_url` for the end-user to pay."}}},"Payment":{"type":"object","description":"Beta. A payment and its current status.","properties":{"id":{"type":"string","description":"Opaque payment id."},"status":{"type":"string","enum":["pending","awaiting_payment","processing","succeeded","failed","refunded"]},"funding_source":{"type":"string","enum":["wallet","collect"]},"biller":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string","nullable":true},"name":{"type":"string"}}},"amount":{"type":"string","example":"1500.00","description":"The bill amount."},"convenience_fee":{"type":"string","example":"20.00","description":"The provider's convenience fee, charged on top of the bill."},"platform_fee":{"type":"string","example":"25.00","description":"Billy's fee for the posting."},"gateway_fee":{"type":"string","example":"0.00","description":"The payment gateway's processing fee, surcharged to the payer on `collect`. Always `0.00` on `wallet`."},"customer_total":{"type":"string","example":"1545.00","description":"What the payer owes: amount + convenience_fee + platform_fee + gateway_fee. On `wallet` this is what leaves your float; on `collect` it is what the end-user pays at checkout."},"refunded_amount":{"type":"string","example":"0.00","description":"Total refunded so far. The refundable ceiling is customer_total excluding gateway_fee."},"currency":{"type":"string","example":"PHP"},"fields":{"type":"object","description":"The biller input fields as submitted.","additionalProperties":{"type":"string"}},"external_customer_ref":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true,"additionalProperties":{"type":"string"}},"reference":{"type":"string","nullable":true,"description":"Biller receipt reference, present once succeeded."},"checkout_url":{"type":"string","nullable":true,"format":"uri","description":"For `collect` payments: the hosted checkout where the end-user pays. Present on creation."},"failure_code":{"type":"string","nullable":true,"description":"Machine-readable reason, present when failed."},"failure_reason":{"type":"string","nullable":true,"description":"Human-readable reason, present when failed."},"created_at":{"type":"string","format":"date-time"}}},"Wallet":{"type":"object","description":"Beta. Your prefunded PHP float. Amounts are decimal strings (2 dp).","properties":{"currency":{"type":"string","example":"PHP"},"available":{"type":"string","example":"8480.00","description":"Spendable balance."},"held":{"type":"string","example":"1520.00","description":"Reserved against in-flight payments."},"total":{"type":"string","example":"10000.00","description":"available + held."},"credit_limit":{"type":"string","example":"0.00","description":"Overdraft allowance for postpaid partners (usually 0.00)."},"spendable":{"type":"string","example":"8480.00","description":"available + credit_limit \u2014 the most a payment can reserve now."}}},"PaymentCollection":{"type":"object","description":"Laravel-style paginated collection of payments.","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Payment"}},"links":{"$ref":"#\/components\/schemas\/PaginationLinks"},"meta":{"$ref":"#\/components\/schemas\/PaginationMeta"}}},"LedgerEntry":{"type":"object","description":"Beta. One line of your wallet statement. A payment shows as several lines as its money moves between your pockets. Amounts are decimal strings (2 dp).","properties":{"type":{"type":"string","enum":["prefund","payment_accept","payment_confirm","payment_reject","refund","adjustment"]},"pocket":{"type":"string","enum":["available","held"],"description":"Which balance this line moved."},"direction":{"type":"string","enum":["credit","debit"]},"amount":{"type":"string","example":"1545.00"},"balance_after":{"type":"string","example":"8455.00","description":"The pocket's balance immediately after this line."},"reference_type":{"type":"string","nullable":true,"example":"Payment"},"created_at":{"type":"string","format":"date-time"}}},"LedgerCollection":{"type":"object","description":"Laravel-style paginated wallet statement.","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/LedgerEntry"}},"links":{"$ref":"#\/components\/schemas\/PaginationLinks"},"meta":{"$ref":"#\/components\/schemas\/PaginationMeta"}}},"TopUpRequest":{"type":"object","description":"Beta. Body for initiating a float top-up.","required":["amount","method"],"properties":{"amount":{"type":"number","format":"float","example":10000,"description":"Amount to fund, in PHP."},"method":{"type":"string","enum":["bank_transfer","magpie"]},"reference":{"type":"string","nullable":true,"description":"Your reference (e.g. a bank transfer memo)."}}},"TopUp":{"type":"object","description":"Beta. A float top-up and its status.","properties":{"id":{"type":"string","description":"Opaque top-up id."},"status":{"type":"string","enum":["pending","confirmed","failed"]},"method":{"type":"string","enum":["bank_transfer","magpie"]},"amount":{"type":"string","example":"10000.00"},"currency":{"type":"string","example":"PHP"},"reference":{"type":"string","nullable":true},"checkout_url":{"type":"string","nullable":true,"format":"uri","description":"Magpie hosted-checkout URL; present on creation for the `magpie` method."},"confirmed_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"RefundRequest":{"type":"object","description":"Beta. Body for refunding a payment. Omit `amount` for a full refund.","properties":{"amount":{"type":"number","format":"float","nullable":true,"example":500,"description":"Amount to refund in PHP; defaults to the full remaining amount."},"reason":{"type":"string","nullable":true}}},"Refund":{"type":"object","description":"Beta. A refund of a payment.","properties":{"id":{"type":"string","description":"Opaque refund id."},"payment_id":{"type":"string"},"status":{"type":"string","enum":["pending","succeeded","failed"]},"amount":{"type":"string","example":"500.00"},"currency":{"type":"string","example":"PHP"},"reason":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"WalletCollection":{"type":"object","description":"Every currency wallet the partner holds.","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Wallet"}}}},"WebhookDelivery":{"type":"object","description":"Beta. One outbound webhook delivery attempt. Dedupe on `id`.","properties":{"id":{"type":"string","description":"Stable event id (dedupe on this).","example":"evt_01hz..."},"event_type":{"type":"string","enum":["payment.processing","payment.succeeded","payment.failed","topup.confirmed","wallet.low_balance"]},"status":{"type":"string","enum":["pending","delivered","failed"]},"attempts":{"type":"integer"},"last_response_status":{"type":"integer","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"WebhookDeliveryCollection":{"type":"object","description":"Laravel-style paginated webhook delivery log.","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/WebhookDelivery"}},"links":{"$ref":"#\/components\/schemas\/PaginationLinks"},"meta":{"$ref":"#\/components\/schemas\/PaginationMeta"}}},"PaginationLinks":{"type":"object","properties":{"first":{"type":"string","nullable":true},"last":{"type":"string","nullable":true},"prev":{"type":"string","nullable":true},"next":{"type":"string","nullable":true}}},"PaginationMeta":{"type":"object","properties":{"current_page":{"type":"integer"},"from":{"type":"integer","nullable":true},"last_page":{"type":"integer"},"path":{"type":"string"},"per_page":{"type":"integer"},"to":{"type":"integer","nullable":true},"total":{"type":"integer"}}},"InsufficientBalanceError":{"type":"object","properties":{"message":{"type":"string","example":"Wallet balance is insufficient for this payment."},"code":{"type":"string","example":"insufficient_balance"}}},"Error":{"type":"object","properties":{"message":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"responses":{"Unauthorized":{"description":"Missing, invalid or revoked API key.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"InsufficientBalance":{"description":"Wallet balance cannot cover the payment. Top up your float and retry.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/InsufficientBalanceError"}}}}}},"paths":{"\/categories":{"get":{"operationId":"listCategories","tags":["Categories"],"summary":"List categories","description":"All biller categories with a count of active billers (`billers_count`).","responses":{"200":{"description":"A list of categories","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Category"}}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"}}}},"\/billers":{"get":{"operationId":"listBillers","tags":["Billers"],"summary":"List billers","description":"Paginated list of billers available to your partner account: all active billers, plus any strict billers your partner has been approved for. Deactivated and unapproved strict billers are never returned.","parameters":[{"name":"status","in":"query","required":false,"description":"Filter by status (active|strict|deactivated). Defaults to active.","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"Filter by category slug, e.g. \"loans\".","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"Filter by biller type (1=Online, 2=Offline, 3=Offline-LUDB).","schema":{"type":"string"}},{"name":"search","in":"query","required":false,"description":"Relevance-ranked full-text search across code, name and description (PostgreSQL full-text with prefix matching; ranked LIKE fallback otherwise).","schema":{"type":"string"}},{"name":"per_page","in":"query","required":false,"description":"Results per page (1\u2013100, default 25).","schema":{"type":"string"}}],"responses":{"200":{"description":"A paginated list of billers","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/BillerCollection"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"}}}},"\/billers\/search":{"get":{"operationId":"searchBillers","tags":["Billers"],"summary":"Typeahead search","description":"Lightweight, relevance-ranked search for autocomplete. Returns minimal fields (id, code, name, logo_thumb_url) for billers available to your partner.","parameters":[{"name":"q","in":"query","required":true,"description":"The search query.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Max results (1\u201325, default 10).","schema":{"type":"string"}}],"responses":{"200":{"description":"Matching biller suggestions","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/BillerSuggestion"}}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"422":{"description":"Missing query","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ValidationError"}}}}}}},"\/billers\/{id}":{"get":{"operationId":"getBiller","tags":["Billers"],"summary":"Get a biller","description":"A single biller with its field schema, current fee and policies. Returns 404 for billers your partner may not access (deactivated, or strict and not approved).","parameters":[{"name":"id","in":"path","required":true,"description":"Public biller id (ULID)","schema":{"type":"string"}}],"responses":{"200":{"description":"The biller","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Biller"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"404":{"description":"Not found","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/billers\/{id}\/quote":{"post":{"operationId":"quotePayment","tags":["Billers"],"summary":"Quote a payment","description":"Compute the customer total and fee breakdown for paying an amount to a biller.\n\n`customer_total = amount + convenience_fee + platform_fee`. The convenience fee is the provider's; the platform fee is Billy's. merchant commission and biller share are settlement-side and shown for transparency.","parameters":[{"name":"id","in":"path","required":true,"description":"Public biller id (ULID)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number","format":"float","example":1500,"description":"Amount to pay, > 0 and within the biller min\/max when set."}}}}}},"responses":{"200":{"description":"The quote","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Quote"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"422":{"description":"Amount invalid or outside the biller min\/max","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ValidationError"}}}}}}},"\/billers\/{id}\/payments":{"post":{"operationId":"createPayment","tags":["Payments"],"summary":"Pay a bill (beta)","description":"**Beta \u2014 rolling out now; the exact contract may change before general availability.**\n\nSubmit a payment to a biller. Money-in and biller settlement are handled by the platform; the payment moves through `pending \u2192 processing \u2192 succeeded`\/`failed`, and each change is delivered to your webhook endpoint.\n\nAlways send an `Idempotency-Key`: a retry with the same key returns the original payment instead of creating a duplicate.","parameters":[{"name":"id","in":"path","required":true,"description":"Public biller id (ULID)","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key (e.g. a UUID) that makes retries safe against double payment.","schema":{"type":"string","example":"8f14e45f-ea28-4e1a-9a2b-1c2d3e4f5a6b"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PaymentRequest"}}}},"responses":{"201":{"description":"Payment accepted","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Payment"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"404":{"description":"Biller not found or not available to your account","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"402":{"$ref":"#\/components\/responses\/InsufficientBalance"},"422":{"description":"Validation error (amount outside min\/max, or fields fail the biller schema)","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ValidationError"}}}}}}},"\/payments\/{id}":{"get":{"operationId":"getPayment","tags":["Payments"],"summary":"Retrieve a payment (beta)","description":"Fetch one of your payments by its opaque id, including its current status and (once succeeded) the biller `reference`.","parameters":[{"name":"id","in":"path","required":true,"description":"Public payment id (ULID)","schema":{"type":"string"}}],"responses":{"200":{"description":"The payment","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Payment"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"404":{"description":"No such payment for your account","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/payments":{"get":{"operationId":"listPayments","tags":["Payments"],"summary":"List payments (beta)","description":"Your payments, most recent first. Filter by status, external_customer_ref and creation date.","parameters":[{"name":"status","in":"query","required":false,"description":"Filter by status (pending|processing|succeeded|failed).","schema":{"type":"string"}},{"name":"external_customer_ref","in":"query","required":false,"description":"Filter by your end-user reference.","schema":{"type":"string"}},{"name":"date","in":"query","required":false,"description":"Filter by creation date (YYYY-MM-DD).","schema":{"type":"string"}},{"name":"per_page","in":"query","required":false,"description":"Results per page (1\u2013100, default 25).","schema":{"type":"string"}}],"responses":{"200":{"description":"A paginated list of payments","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PaymentCollection"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"}}}},"\/wallet":{"get":{"operationId":"getWallet","tags":["Wallet"],"summary":"Get wallet balance (beta)","description":"Your prefunded PHP float. `available` is spendable; `held` is reserved against in-flight payments; `total` is `available + held`. A payment reserves `customer_total` from `available` into `held`; top up ahead of usage.","responses":{"200":{"description":"Wallet balance","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Wallet"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"}}}},"\/wallet\/ledger":{"get":{"operationId":"getWalletLedger","tags":["Wallet"],"summary":"Wallet statement (beta)","description":"Paginated ledger entries for your float, most recent first \u2014 the authoritative record of every balance movement.","parameters":[{"name":"per_page","in":"query","required":false,"description":"Results per page (1\u2013100, default 50).","schema":{"type":"string"}}],"responses":{"200":{"description":"A paginated wallet statement","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/LedgerCollection"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"}}}},"\/top-ups":{"post":{"operationId":"createTopUp","tags":["Top-ups"],"summary":"Initiate a float top-up (beta)","description":"Fund your PHP float via `bank_transfer` (manual, confirmed out of band) or `magpie` (card\/e-wallet; returns a `checkout_url`). The wallet is credited when the funds are confirmed, not at creation.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TopUpRequest"}}}},"responses":{"201":{"description":"Top-up initiated","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/TopUp"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"422":{"description":"Validation error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ValidationError"}}}}}}},"\/top-ups\/{id}":{"get":{"operationId":"getTopUp","tags":["Top-ups"],"summary":"Retrieve a top-up (beta)","description":"Track a float top-up by its opaque id.","parameters":[{"name":"id","in":"path","required":true,"description":"Public top-up id (ULID)","schema":{"type":"string"}}],"responses":{"200":{"description":"The top-up","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/TopUp"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"404":{"description":"No such top-up for your account","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/webhooks\/deliveries":{"get":{"operationId":"listWebhookDeliveries","tags":["Webhooks"],"summary":"List webhook deliveries (beta)","description":"Your outbound webhook delivery attempts across all endpoints, most recent first. Filter by status and event type.","parameters":[{"name":"status","in":"query","required":false,"description":"Filter by status (pending|delivered|failed).","schema":{"type":"string"}},{"name":"event_type","in":"query","required":false,"description":"Filter by event type, e.g. payment.succeeded.","schema":{"type":"string"}},{"name":"per_page","in":"query","required":false,"description":"Results per page (1\u2013100, default 50).","schema":{"type":"string"}}],"responses":{"200":{"description":"A paginated delivery log","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/WebhookDeliveryCollection"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"}}}},"\/payments\/{id}\/refunds":{"get":{"operationId":"listRefunds","tags":["Payments"],"summary":"List a payment's refunds (beta)","parameters":[{"name":"id","in":"path","required":true,"description":"Public payment id (ULID)","schema":{"type":"string"}}],"responses":{"200":{"description":"The payment's refunds","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Refund"}}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"404":{"description":"No such payment","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}},"post":{"operationId":"createRefund","tags":["Payments"],"summary":"Refund a payment (beta)","description":"Refund a succeeded payment, fully or partially. Wallet-funded payments credit your float; \"Billy collects\" payments refund the end-user.","parameters":[{"name":"id","in":"path","required":true,"description":"Public payment id (ULID)","schema":{"type":"string"}}],"requestBody":{"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/RefundRequest"}}}},"responses":{"201":{"description":"Refund created","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Refund"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"404":{"description":"No such payment","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Not refundable, or amount exceeds the remaining refundable amount","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ValidationError"}}}}}}},"\/wallets":{"get":{"operationId":"listWallets","tags":["Wallet"],"summary":"List all currency wallets (beta)","description":"Every currency wallet you hold. Bills settle in PHP today; additional currencies appear here as they are funded.","responses":{"200":{"description":"Your wallets","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/WalletCollection"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"}}}}}}