{"openapi":"3.1.0","info":{"title":"Kwiikpay Partner API","version":"0.0.1","description":"\n# Kwiikpay Partner API\n\nProgrammatic access to KYC/KYB onboarding, virtual IBANs, payments, FX conversions and crypto — for KwiikPay programme partners.\n\n## Base URL\n```\nhttps://api-next.kwiikpay.io\n```\nAll partner endpoints live under `/v1/partner`.\n\n## Authentication\nSend your **public key** as a Bearer token on every request:\n```\nAuthorization: Bearer kp_pub_xxxxxxxxxxxxxxxxxxxxxxxx\n```\nYour `kp_sec_…` secret is shown once at issuance — keep it server-side. Never expose either key in browser or mobile client code; call the API from your backend.\n\n## Response envelope\nEvery response uses the same shape:\n```json\n{ \"success\": true, \"status_code\": 200, \"message\": \"…\", \"data\": { } }\n```\nOn failure, `success` is `false` and `errors` carries field-level detail:\n```json\n{ \"success\": false, \"status_code\": 422, \"message\": \"Validation failed\", \"errors\": { \"amount\": [\"must be positive\"] } }\n```\n\n## The typical flow\n1. **Create a customer** — `POST /v1/partner/customers`\n2. **Run KYC / KYB** — initiate verification, redirect the customer to the hosted link, wait for the `verification.updated` webhook\n3. **Open a virtual IBAN** — once verified, provision an account for pay-ins\n4. **Move money** — receive funds, run FX **conversions**, initiate **payouts**, or send **crypto**\n5. **React to webhooks** — subscribe an endpoint to be notified as state changes\n\n## Webhooks\nRegister a delivery endpoint via `POST /v1/partner/webhooks/endpoint`. You receive a **signing secret once** — verify the signature on every incoming event before trusting it. Redeliver or inspect past attempts from the same section.\n\n## Support\nRaise and track issues via the **Support** endpoints, or contact your KwiikPay integration manager.\n"},"servers":[{"url":"https://api-next.kwiikpay.io","description":"Production"}],"tags":[{"name":"Partner","description":"Your programme: who you are, and your pricing."},{"name":"Customers","description":"The people and businesses you onboard."},{"name":"Onboarding","description":"Profile data, and what a provider still needs before an account can open."},{"name":"Verifications","description":"KYC/KYB — run it, check it, or reuse a verification you already hold."},{"name":"Banking","description":"Virtual IBANs, wallets, balances and payout beneficiaries."},{"name":"Payouts","description":"Send fiat to a beneficiary."},{"name":"Conversions","description":"FX and crypto conversion: indicative rates, then firm quotes you approve."},{"name":"Crypto","description":"Custody wallets and on-chain deposits."},{"name":"Crypto Payouts","description":"Send crypto to an address or a saved beneficiary."},{"name":"History","description":"A unified transaction feed with fees."},{"name":"Webhooks","description":"Register your delivery endpoint and inspect what we sent."},{"name":"Support","description":"Raise and track issues with KwiikPay."},{"name":"Team","description":"Members of your programme."},{"name":"Metering","description":"Your usage and billing."},{"name":"Monitoring","description":"Transaction-monitoring alerts raised against your customers."},{"name":"Auth","description":"Sign-in for the KwiikPay partner **portal** (email + session cookie). Not part of API integration — API calls authenticate with your `kp_pub_` key instead."}],"components":{"securitySchemes":{"partnerApiKey":{"type":"http","scheme":"bearer","description":"Program public key sent as a Bearer token (Authorization: Bearer kp_pub_…)."}},"schemas":{},"parameters":{}},"paths":{"/v1/partner/me":{"get":{"tags":["Partner"],"summary":"Return the authenticated program","security":[{"partnerApiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","sandbox","suspended","sunset"]},"fees":{"type":"object","properties":{"fx_fee_bps":{"type":"integer","minimum":0,"maximum":10000},"stablecoin_fee_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_fee_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_fee_fixed_minor":{"type":"integer","minimum":0},"incoming_fee_fixed_minor":{"type":"integer","minimum":0},"maintenance_monthly_minor":{"type":"integer","minimum":0}},"required":["fx_fee_bps","stablecoin_fee_bps","withdrawal_fee_bps","withdrawal_fee_fixed_minor","incoming_fee_fixed_minor","maintenance_monthly_minor"]},"brand_name":{"type":["string","null"]},"brand_color_primary":{"type":["string","null"]}},"required":["fees","brand_name","brand_color_primary"]}},"required":["success","status_code"]}}}},"401":{"description":"Unauthenticated"}}}},"/v1/partner/pricing":{"get":{"tags":["Partner"],"summary":"Get KP floor fees (read-only) + your markup (editable)","security":[{"partnerApiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"floor":{"type":"object","properties":{"fx_fee_bps":{"type":"integer","minimum":0,"maximum":10000},"stablecoin_fee_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_fee_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_fee_fixed_minor":{"type":"integer","minimum":0},"incoming_fee_fixed_minor":{"type":"integer","minimum":0},"maintenance_monthly_minor":{"type":"integer","minimum":0}},"required":["fx_fee_bps","stablecoin_fee_bps","withdrawal_fee_bps","withdrawal_fee_fixed_minor","incoming_fee_fixed_minor","maintenance_monthly_minor"]},"markup":{"type":"object","properties":{"fx_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"stablecoin_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_markup_fixed_minor":{"type":"integer","minimum":0},"incoming_markup_fixed_minor":{"type":"integer","minimum":0}},"required":["fx_markup_bps","stablecoin_markup_bps","withdrawal_markup_bps","withdrawal_markup_fixed_minor","incoming_markup_fixed_minor"]}},"required":["floor","markup"]}},"required":["success","status_code"]}}}}}},"put":{"tags":["Partner"],"summary":"Set your markup (what you earn on top of KP fees)","security":[{"partnerApiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fx_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"stablecoin_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_markup_fixed_minor":{"type":"integer","minimum":0},"incoming_markup_fixed_minor":{"type":"integer","minimum":0}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"fx_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"stablecoin_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_markup_fixed_minor":{"type":"integer","minimum":0},"incoming_markup_fixed_minor":{"type":"integer","minimum":0}},"required":["fx_markup_bps","stablecoin_markup_bps","withdrawal_markup_bps","withdrawal_markup_fixed_minor","incoming_markup_fixed_minor"]}},"required":["success","status_code"]}}}}}}},"/v1/partner/customers/{id}/pricing":{"get":{"tags":["Partner"],"summary":"Get this customer’s effective pricing (KP floor + global markup + their override)","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"floor":{"type":"object","properties":{"fx_fee_bps":{"type":"integer","minimum":0,"maximum":10000},"stablecoin_fee_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_fee_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_fee_fixed_minor":{"type":"integer","minimum":0},"incoming_fee_fixed_minor":{"type":"integer","minimum":0},"maintenance_monthly_minor":{"type":"integer","minimum":0}},"required":["fx_fee_bps","stablecoin_fee_bps","withdrawal_fee_bps","withdrawal_fee_fixed_minor","incoming_fee_fixed_minor","maintenance_monthly_minor"]},"program_markup":{"type":"object","properties":{"fx_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"stablecoin_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_markup_fixed_minor":{"type":"integer","minimum":0},"incoming_markup_fixed_minor":{"type":"integer","minimum":0}},"required":["fx_markup_bps","stablecoin_markup_bps","withdrawal_markup_bps","withdrawal_markup_fixed_minor","incoming_markup_fixed_minor"]},"override":{"type":["object","null"],"properties":{"fx_markup_bps":{"type":["integer","null"],"minimum":0,"maximum":10000},"stablecoin_markup_bps":{"type":["integer","null"],"minimum":0,"maximum":10000}},"required":["fx_markup_bps","stablecoin_markup_bps"]},"effective":{"type":"object","properties":{"fx_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"stablecoin_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_markup_fixed_minor":{"type":"integer","minimum":0},"incoming_markup_fixed_minor":{"type":"integer","minimum":0}},"required":["fx_markup_bps","stablecoin_markup_bps","withdrawal_markup_bps","withdrawal_markup_fixed_minor","incoming_markup_fixed_minor"]}},"required":["floor","program_markup","override","effective"]}},"required":["success","status_code"]}}}},"404":{"description":"Customer not found"}}},"put":{"tags":["Partner"],"summary":"Set a special markup for this customer (null field = inherit your global markup)","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fx_markup_bps":{"type":["integer","null"],"minimum":0,"maximum":10000},"stablecoin_markup_bps":{"type":["integer","null"],"minimum":0,"maximum":10000}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"floor":{"type":"object","properties":{"fx_fee_bps":{"type":"integer","minimum":0,"maximum":10000},"stablecoin_fee_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_fee_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_fee_fixed_minor":{"type":"integer","minimum":0},"incoming_fee_fixed_minor":{"type":"integer","minimum":0},"maintenance_monthly_minor":{"type":"integer","minimum":0}},"required":["fx_fee_bps","stablecoin_fee_bps","withdrawal_fee_bps","withdrawal_fee_fixed_minor","incoming_fee_fixed_minor","maintenance_monthly_minor"]},"program_markup":{"type":"object","properties":{"fx_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"stablecoin_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_markup_fixed_minor":{"type":"integer","minimum":0},"incoming_markup_fixed_minor":{"type":"integer","minimum":0}},"required":["fx_markup_bps","stablecoin_markup_bps","withdrawal_markup_bps","withdrawal_markup_fixed_minor","incoming_markup_fixed_minor"]},"override":{"type":["object","null"],"properties":{"fx_markup_bps":{"type":["integer","null"],"minimum":0,"maximum":10000},"stablecoin_markup_bps":{"type":["integer","null"],"minimum":0,"maximum":10000}},"required":["fx_markup_bps","stablecoin_markup_bps"]},"effective":{"type":"object","properties":{"fx_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"stablecoin_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_markup_fixed_minor":{"type":"integer","minimum":0},"incoming_markup_fixed_minor":{"type":"integer","minimum":0}},"required":["fx_markup_bps","stablecoin_markup_bps","withdrawal_markup_bps","withdrawal_markup_fixed_minor","incoming_markup_fixed_minor"]}},"required":["floor","program_markup","override","effective"]}},"required":["success","status_code"]}}}},"404":{"description":"Customer not found"}}},"delete":{"tags":["Partner"],"summary":"Reset a customer to your global markup (clear their override)","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"floor":{"type":"object","properties":{"fx_fee_bps":{"type":"integer","minimum":0,"maximum":10000},"stablecoin_fee_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_fee_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_fee_fixed_minor":{"type":"integer","minimum":0},"incoming_fee_fixed_minor":{"type":"integer","minimum":0},"maintenance_monthly_minor":{"type":"integer","minimum":0}},"required":["fx_fee_bps","stablecoin_fee_bps","withdrawal_fee_bps","withdrawal_fee_fixed_minor","incoming_fee_fixed_minor","maintenance_monthly_minor"]},"program_markup":{"type":"object","properties":{"fx_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"stablecoin_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_markup_fixed_minor":{"type":"integer","minimum":0},"incoming_markup_fixed_minor":{"type":"integer","minimum":0}},"required":["fx_markup_bps","stablecoin_markup_bps","withdrawal_markup_bps","withdrawal_markup_fixed_minor","incoming_markup_fixed_minor"]},"override":{"type":["object","null"],"properties":{"fx_markup_bps":{"type":["integer","null"],"minimum":0,"maximum":10000},"stablecoin_markup_bps":{"type":["integer","null"],"minimum":0,"maximum":10000}},"required":["fx_markup_bps","stablecoin_markup_bps"]},"effective":{"type":"object","properties":{"fx_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"stablecoin_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_markup_bps":{"type":"integer","minimum":0,"maximum":10000},"withdrawal_markup_fixed_minor":{"type":"integer","minimum":0},"incoming_markup_fixed_minor":{"type":"integer","minimum":0}},"required":["fx_markup_bps","stablecoin_markup_bps","withdrawal_markup_bps","withdrawal_markup_fixed_minor","incoming_markup_fixed_minor"]}},"required":["floor","program_markup","override","effective"]}},"required":["success","status_code"]}}}},"404":{"description":"Customer not found"}}}},"/v1/partner/customers":{"post":{"tags":["Customers"],"summary":"Create a customer","security":[{"partnerApiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"type":{"type":"string","enum":["individual","business"]},"legal_name":{"type":"string","maxLength":255}},"required":["email"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"program_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["individual","business"]},"email":{"type":"string","format":"email"},"legal_name":{"type":["string","null"]},"status":{"type":"string","enum":["created","onboarding","verified","active","suspended","rejected"]},"profile":{"type":"object","additionalProperties":{}},"created_at":{"type":"string"}},"required":["id","program_id","type","email","legal_name","status","profile","created_at"]}},"required":["success","status_code"]}}}},"409":{"description":"Email already exists for this program"}}},"get":{"tags":["Customers"],"summary":"List customers","description":"Lists the programme's customers. Pass `q` to search (case-insensitive) across email, legal name, customer id, phone, registration number, date of birth, country and nationality. Omit `page`/`limit` to return every customer (unpaginated); pass them to page through results — `meta.total` carries the full match count.","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":200},"required":false,"name":"q","in":"query"},{"schema":{"type":"string"},"required":false,"name":"page","in":"query"},{"schema":{"type":"string"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"program_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["individual","business"]},"email":{"type":"string","format":"email"},"legal_name":{"type":["string","null"]},"status":{"type":"string","enum":["created","onboarding","verified","active","suspended","rejected"]},"profile":{"type":"object","additionalProperties":{}},"created_at":{"type":"string"}},"required":["id","program_id","type","email","legal_name","status","profile","created_at"]}},"meta":{"type":"object","properties":{"total":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"}},"required":["total","page","limit"]}},"required":["success","status_code"]}}}}}}},"/v1/partner/customers/{id}":{"get":{"tags":["Customers"],"summary":"Get a customer","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"program_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["individual","business"]},"email":{"type":"string","format":"email"},"legal_name":{"type":["string","null"]},"status":{"type":"string","enum":["created","onboarding","verified","active","suspended","rejected"]},"profile":{"type":"object","additionalProperties":{}},"created_at":{"type":"string"}},"required":["id","program_id","type","email","legal_name","status","profile","created_at"]}},"required":["success","status_code"]}}}},"404":{"description":"Not found"}}}},"/v1/partner/customers/{customerId}/verifications":{"post":{"tags":["Verifications"],"summary":"Initiate KYC/KYB for a customer","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["kyc","kyb"]}},"required":["kind"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["kyc","kyb"]},"provider":{"type":"string","enum":["sumsub","manual"]},"provider_ref":{"type":["string","null"]},"status":{"type":"string","enum":["pending","in_review","needs_info","approved","rejected"]},"risk_decision":{"type":"string","enum":["pending","cleared","manual_review","blocked"]},"required_action":{},"reason":{"type":["string","null"]},"submitted_at":{"type":["string","null"]},"decided_at":{"type":["string","null"]},"created_at":{"type":"string"},"sdk_token":{"type":["string","null"]}},"required":["id","customer_id","kind","provider","provider_ref","status","risk_decision","reason","submitted_at","decided_at","created_at"]}},"required":["success","status_code"]}}}},"404":{"description":"Customer not found"}}},"get":{"tags":["Verifications"],"summary":"List a customer’s verifications","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["kyc","kyb"]},"provider":{"type":"string","enum":["sumsub","manual"]},"provider_ref":{"type":["string","null"]},"status":{"type":"string","enum":["pending","in_review","needs_info","approved","rejected"]},"risk_decision":{"type":"string","enum":["pending","cleared","manual_review","blocked"]},"required_action":{},"reason":{"type":["string","null"]},"submitted_at":{"type":["string","null"]},"decided_at":{"type":["string","null"]},"created_at":{"type":"string"},"sdk_token":{"type":["string","null"]}},"required":["id","customer_id","kind","provider","provider_ref","status","risk_decision","reason","submitted_at","decided_at","created_at"]}}},"required":["success","status_code"]}}}}}}},"/v1/partner/customers/{customerId}/verifications/reuse":{"post":{"tags":["Verifications"],"summary":"Reuse a verification already done on the partner’s own Sumsub","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["kyc","kyb"]},"share_token":{"type":"string","minLength":1},"consent_attested":{"type":"boolean"},"consent_reference":{"type":"string"}},"required":["kind","share_token","consent_attested"]}}}},"responses":{"201":{"description":"Imported","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["kyc","kyb"]},"provider":{"type":"string","enum":["sumsub","manual"]},"provider_ref":{"type":["string","null"]},"status":{"type":"string","enum":["pending","in_review","needs_info","approved","rejected"]},"risk_decision":{"type":"string","enum":["pending","cleared","manual_review","blocked"]},"required_action":{},"reason":{"type":["string","null"]},"submitted_at":{"type":["string","null"]},"decided_at":{"type":["string","null"]},"created_at":{"type":"string"},"sdk_token":{"type":["string","null"]}},"required":["id","customer_id","kind","provider","provider_ref","status","risk_decision","reason","submitted_at","decided_at","created_at"]}},"required":["success","status_code"]}}}},"400":{"description":"Consent not attested / missing share token"},"404":{"description":"Customer not found"}}}},"/v1/partner/customers/{customerId}/verification-link":{"get":{"tags":["Verifications"],"summary":"Get a hosted KYC/KYB link to send to the customer","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"},{"schema":{"type":"string","enum":["kyc","kyb"],"default":"kyc"},"required":false,"name":"kind","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"url":{"type":["string","null"]},"kind":{"type":"string","enum":["kyc","kyb"]}},"required":["url","kind"]}},"required":["success","status_code"]}}}}}}},"/v1/partner/customers/{customerId}/verifications/{verificationId}/details":{"get":{"tags":["Verifications"],"summary":"Full KYC/KYB details from the provider","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"verificationId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":["object","null"],"properties":{"inspection_id":{"type":["string","null"]},"external_user_id":{"type":["string","null"]},"applicant_type":{"type":["string","null"]},"created_at":{"type":["string","null"]},"identity":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"full_name":{"type":"string"},"dob":{"type":"string"},"nationality":{"type":"string"},"country":{"type":"string"},"gender":{"type":"string"},"place_of_birth":{"type":"string"}}},"address":{"type":["object","null"],"properties":{"line":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"},"formatted":{"type":"string"}}},"review":{"type":"object","properties":{"answer":{"type":"string"},"status":{"type":"string"},"reject_type":{"type":"string"},"reject_labels":{"type":"array","items":{"type":"string"}},"moderation_comment":{"type":"string"},"client_comment":{"type":"string"},"reviewed_at":{"type":"string"}},"required":["reject_labels"]},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"doc_type":{"type":"string"},"country":{"type":"string"},"number":{"type":"string"},"valid_until":{"type":"string"},"issued_date":{"type":"string"},"status":{"type":["string","null"]},"reject_labels":{"type":"array","items":{"type":"string"}},"images":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"review_answer":{"type":"string"}},"required":["id"]}}},"required":["type","status","reject_labels","images"]}},"company":{"type":["object","null"],"properties":{"name":{"type":"string"},"registration_number":{"type":"string"},"incorporated_on":{"type":"string"},"type":{"type":"string"},"country":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"website":{"type":"string"},"address":{"type":"object","properties":{"line":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"},"formatted":{"type":"string"}}}}},"beneficiaries":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"role":{"type":"string"},"positions":{"type":"array","items":{"type":"string"}},"share":{"type":"number"},"applicant_id":{"type":"string"}}}}},"required":["inspection_id","external_user_id","applicant_type","created_at","identity","address","review","documents","company","beneficiaries"]}},"required":["success","status_code"]}}}},"404":{"description":"Verification not found"}}}},"/v1/partner/customers/{customerId}/monitoring":{"get":{"tags":["Monitoring"],"summary":"Transaction-monitoring alerts for a customer","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"subject_type":{"type":"string","enum":["deposit","conversion","payout"]},"subject_id":{"type":"string"},"direction":{"type":"string"},"asset":{"type":"string"},"amount":{"type":"string"},"score":{"type":"number"},"severity":{"type":"string","enum":["low","medium","high"]},"rules":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"score":{"type":"number"}},"required":["code","title","score"]}},"status":{"type":"string","enum":["open","cleared","escalated","reported"]},"provider":{"type":"string"},"resolution":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","customer_id","subject_type","subject_id","direction","asset","amount","score","severity","rules","status","provider","resolution","created_at"]}}},"required":["success","status_code"]}}}}}}},"/v1/partner/customers/{customerId}/profile":{"patch":{"tags":["Onboarding"],"summary":"Update a customer’s canonical profile","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"legal_name":{"type":"string","maxLength":255},"display_name":{"type":"string","maxLength":255},"address_line1":{"type":"string","maxLength":255},"address_line2":{"type":"string","maxLength":255},"city":{"type":"string","maxLength":100},"postal_code":{"type":"string","maxLength":20},"country":{"type":"string","maxLength":2},"date_of_birth":{"type":"string"},"id_number":{"type":"string","maxLength":100},"id_type":{"type":"string","maxLength":50,"description":"PASSPORT | NATIONAL_ID | DRIVERS_LICENCE | WORK_PERMIT (free text; mapped to the provider’s enum)."},"email":{"type":"string","maxLength":255,"format":"email"},"phone":{"type":"string","maxLength":32},"nationality":{"type":"string","maxLength":2}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string"},"profile":{"type":"object","additionalProperties":{}}},"required":["id","profile"]}},"required":["success","status_code"]}}}},"404":{"description":"Customer not found"}}}},"/v1/partner/customers/{customerId}/readiness":{"get":{"tags":["Onboarding"],"summary":"Check provider-readiness before account opening","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"provider":{"type":"string","enum":["bcb","fiat-republic"]},"ready":{"type":"boolean"},"issues":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"label":{"type":"string"},"problem":{"type":"string","enum":["missing","non_latin","too_long","too_few_words"]},"group":{"type":"string"}},"required":["field","label","problem"]}},"checklist":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"label":{"type":"string"},"group":{"type":"string"},"ok":{"type":"boolean"},"value":{"type":"string"},"problem":{"type":"string","enum":["missing","non_latin","too_long","too_few_words"]},"requiredFor":{"type":"string","enum":["GBP","EUR","USD"]}},"required":["field","label","group","ok"]}}},"required":["provider","ready","issues"]}},"required":["success","status_code"]}}}},"404":{"description":"Customer not found"}}}},"/v1/partner/customers/{customerId}/accounts":{"post":{"tags":["Banking"],"summary":"Open a virtual account (vIBAN) — gated by provider readiness + country risk","description":"Opens a vIBAN. The response carries a `compliance` block with the banking partner's country-risk verdict. A customer resident in a PROHIBITED jurisdiction is refused with 422 (no account is created). A HIGH-risk jurisdiction is created but flagged `enhanced_due_diligence: true` — approval may take longer and further documents may be requested.\n\nSend an **`Idempotency-Key`** header. This opens a real bank account, and where a programme may hold several accounts in one currency we cannot otherwise distinguish \"open me another account\" from \"my request timed out, retrying\" — they are the same call. The same key replays the original response; a new key opens a new account.","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string","enum":["GBP","EUR","USD"]},"label":{"type":"string","minLength":1,"maxLength":255,"description":"Display name for the account, passed to the banking partner. Defaults to the customer's legal name."}},"required":["currency"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"provider":{"type":"string","enum":["bcb","fiat-republic"]},"currency":{"type":"string","enum":["GBP","EUR","USD"]},"label":{"type":["string","null"]},"iban":{"type":["string","null"]},"bic":{"type":["string","null"]},"account_holder":{"type":["string","null"]},"bank_name":{"type":["string","null"]},"account_number":{"type":["string","null"]},"sort_code":{"type":["string","null"]},"routing_number":{"type":["string","null"]},"status":{"type":"string","enum":["pending","active","suspended","closed","failed"]},"status_reason":{"type":["string","null"]},"created_at":{"type":"string"},"balance_minor":{"type":["number","null"]},"posted_minor":{"type":["number","null"]},"compliance":{"type":["object","null"],"properties":{"country":{"type":"string"},"country_name":{"type":"string"},"country_risk":{"type":"string","enum":["low","medium","high","prohibited","unknown"]},"enhanced_due_diligence":{"type":"boolean"},"message":{"type":"string"}},"required":["country","country_name","country_risk","enhanced_due_diligence"]}},"required":["id","customer_id","provider","currency","label","iban","bic","account_holder","bank_name","account_number","sort_code","routing_number","status","status_reason","created_at","balance_minor","posted_minor"]}},"required":["success","status_code"]}}}},"404":{"description":"Customer not found"},"422":{"description":"Not provider-ready, or the customer's country is prohibited by the banking partner"}}},"get":{"tags":["Banking"],"summary":"List virtual accounts","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"provider":{"type":"string","enum":["bcb","fiat-republic"]},"currency":{"type":"string","enum":["GBP","EUR","USD"]},"label":{"type":["string","null"]},"iban":{"type":["string","null"]},"bic":{"type":["string","null"]},"account_holder":{"type":["string","null"]},"bank_name":{"type":["string","null"]},"account_number":{"type":["string","null"]},"sort_code":{"type":["string","null"]},"routing_number":{"type":["string","null"]},"status":{"type":"string","enum":["pending","active","suspended","closed","failed"]},"status_reason":{"type":["string","null"]},"created_at":{"type":"string"},"balance_minor":{"type":["number","null"]},"posted_minor":{"type":["number","null"]},"compliance":{"type":["object","null"],"properties":{"country":{"type":"string"},"country_name":{"type":"string"},"country_risk":{"type":"string","enum":["low","medium","high","prohibited","unknown"]},"enhanced_due_diligence":{"type":"boolean"},"message":{"type":"string"}},"required":["country","country_name","country_risk","enhanced_due_diligence"]}},"required":["id","customer_id","provider","currency","label","iban","bic","account_holder","bank_name","account_number","sort_code","routing_number","status","status_reason","created_at","balance_minor","posted_minor"]}}},"required":["success","status_code"]}}}}}}},"/v1/partner/customers/{customerId}/accounts/{accountId}/status":{"post":{"tags":["Banking"],"summary":"Suspend, reactivate or close a virtual account","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"accountId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["suspend","reactivate","close"]}},"required":["action"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"provider":{"type":"string","enum":["bcb","fiat-republic"]},"currency":{"type":"string","enum":["GBP","EUR","USD"]},"label":{"type":["string","null"]},"iban":{"type":["string","null"]},"bic":{"type":["string","null"]},"account_holder":{"type":["string","null"]},"bank_name":{"type":["string","null"]},"account_number":{"type":["string","null"]},"sort_code":{"type":["string","null"]},"routing_number":{"type":["string","null"]},"status":{"type":"string","enum":["pending","active","suspended","closed","failed"]},"status_reason":{"type":["string","null"]},"created_at":{"type":"string"},"balance_minor":{"type":["number","null"]},"posted_minor":{"type":["number","null"]},"compliance":{"type":["object","null"],"properties":{"country":{"type":"string"},"country_name":{"type":"string"},"country_risk":{"type":"string","enum":["low","medium","high","prohibited","unknown"]},"enhanced_due_diligence":{"type":"boolean"},"message":{"type":"string"}},"required":["country","country_name","country_risk","enhanced_due_diligence"]}},"required":["id","customer_id","provider","currency","label","iban","bic","account_holder","bank_name","account_number","sort_code","routing_number","status","status_reason","created_at","balance_minor","posted_minor"]}},"required":["success","status_code"]}}}},"404":{"description":"Account not found"},"409":{"description":"Illegal lifecycle transition"}}}},"/v1/partner/customers/{customerId}/wallets":{"post":{"tags":["Banking"],"summary":"Open a fiat wallet for a customer (per currency)","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string","enum":["GBP","EUR","USD"]}},"required":["currency"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["success","status_code"]}}}},"404":{"description":"Customer not found"}}}},"/v1/partner/customers/{customerId}/balance":{"get":{"tags":["Banking"],"summary":"Per-currency wallet balances for a customer","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["success","status_code"]}}}}}}},"/v1/partner/customers/{customerId}/beneficiaries":{"post":{"tags":["Banking"],"summary":"Create a beneficiary","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["fiat","crypto"]},"label":{"type":"string","maxLength":255},"ownership":{"type":"string","enum":["self","third_party"],"description":"Whose account this is. `third_party` — paying someone other than the customer — carries a different AML posture."},"entity_type":{"type":"string","enum":["person","business"],"description":"Whether the payee is a natural person or a company."},"details":{"type":"object","additionalProperties":{}}},"required":["type","details"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["fiat","crypto"]},"label":{"type":["string","null"]},"ownership":{"type":["string","null"],"enum":["self","third_party"]},"entity_type":{"type":["string","null"],"enum":["person","business"]},"details":{"type":"object","additionalProperties":{}},"created_at":{"type":"string"}},"required":["id","customer_id","type","label","ownership","entity_type","details","created_at"]}},"required":["success","status_code"]}}}},"404":{"description":"Customer not found"}}},"get":{"tags":["Banking"],"summary":"List beneficiaries","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["fiat","crypto"]},"label":{"type":["string","null"]},"ownership":{"type":["string","null"],"enum":["self","third_party"]},"entity_type":{"type":["string","null"],"enum":["person","business"]},"details":{"type":"object","additionalProperties":{}},"created_at":{"type":"string"}},"required":["id","customer_id","type","label","ownership","entity_type","details","created_at"]}}},"required":["success","status_code"]}}}}}}},"/v1/partner/customers/{customerId}/beneficiaries/{beneficiaryId}":{"delete":{"tags":["Banking"],"summary":"Delete a beneficiary","description":"Retires the beneficiary: it disappears from the list and can no longer be used as a payout destination. Payouts already made to it keep resolving, so payment history stays intact. Deleting an already-deleted beneficiary returns 404.","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"beneficiaryId","in":"path"}],"responses":{"200":{"description":"OK"},"404":{"description":"Not found"}}}},"/v1/partner/customers/{customerId}/payouts":{"post":{"tags":["Payouts"],"summary":"Create a payout (reserves funds; lands at pending_approval)","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"beneficiary_id":{"type":"string","format":"uuid"},"amount":{"type":"integer","exclusiveMinimum":0},"currency":{"type":"string","enum":["GBP","EUR","USD"]},"reference":{"type":"string","minLength":1,"maxLength":17,"pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","description":"What the recipient sees on their statement. Max 17 characters. Defaults to a generated reference."}},"required":["beneficiary_id","amount","currency"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"beneficiary_id":{"type":"string","format":"uuid"},"currency":{"type":"string","enum":["GBP","EUR","USD"]},"amount":{"type":"number"},"reference":{"type":["string","null"]},"kp_fee":{"type":"number"},"provider_cost":{"type":"number"},"total_debit":{"type":"number"},"status":{"type":"string","enum":["initiated","validated","pending_approval","approved","submitted","processing","settled","failed","returned"]},"provider_ref":{"type":["string","null"]},"failure_reason":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","customer_id","beneficiary_id","currency","amount","reference","kp_fee","provider_cost","total_debit","status","provider_ref","failure_reason","created_at"]}},"required":["success","status_code"]}}}},"404":{"description":"Customer/beneficiary not found"},"422":{"description":"Insufficient funds"}}},"get":{"tags":["Payouts"],"summary":"List payouts","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"beneficiary_id":{"type":"string","format":"uuid"},"currency":{"type":"string","enum":["GBP","EUR","USD"]},"amount":{"type":"number"},"reference":{"type":["string","null"]},"kp_fee":{"type":"number"},"provider_cost":{"type":"number"},"total_debit":{"type":"number"},"status":{"type":"string","enum":["initiated","validated","pending_approval","approved","submitted","processing","settled","failed","returned"]},"provider_ref":{"type":["string","null"]},"failure_reason":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","customer_id","beneficiary_id","currency","amount","reference","kp_fee","provider_cost","total_debit","status","provider_ref","failure_reason","created_at"]}}},"required":["success","status_code"]}}}}}}},"/v1/partner/payouts":{"get":{"tags":["Payouts"],"summary":"List all payouts in the programme","security":[{"partnerApiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"beneficiary_id":{"type":"string","format":"uuid"},"currency":{"type":"string","enum":["GBP","EUR","USD"]},"amount":{"type":"number"},"reference":{"type":["string","null"]},"kp_fee":{"type":"number"},"provider_cost":{"type":"number"},"total_debit":{"type":"number"},"status":{"type":"string","enum":["initiated","validated","pending_approval","approved","submitted","processing","settled","failed","returned"]},"provider_ref":{"type":["string","null"]},"failure_reason":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","customer_id","beneficiary_id","currency","amount","reference","kp_fee","provider_cost","total_debit","status","provider_ref","failure_reason","created_at"]}}},"required":["success","status_code"]}}}}}}},"/v1/partner/customers/{customerId}/crypto-payouts":{"post":{"tags":["Crypto Payouts"],"summary":"Create a crypto payout (screens the destination, then auto-approves or queues)","description":"Send to a saved crypto beneficiary with `beneficiary_id`, or to a one-off `address`. Exactly one is required; supplying both is only accepted when they agree. The destination is screened before the payout is approved.","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"asset":{"type":"string","enum":["BTC","ETH","USDT","USDC"]},"amount":{"type":"string","minLength":1},"address":{"type":"string","minLength":1,"description":"Raw destination address, for a one-off send."},"beneficiary_id":{"type":"string","format":"uuid","description":"A saved crypto beneficiary to send to, instead of a raw address."}},"required":["asset","amount"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"asset":{"type":"string","enum":["BTC","ETH","USDT","USDC"]},"amount":{"type":"string"},"network":{"type":["string","null"]},"beneficiary_id":{"type":["string","null"],"format":"uuid"},"destination_address":{"type":"string"},"status":{"type":"string","enum":["initiated","pending_approval","approved","submitted","processing","settled","blocked","failed"]},"kp_fee_amount":{"type":"string"},"screening":{"type":"object","properties":{"provider":{"type":["string","null"]},"decision":{"type":["string","null"]},"risk":{"type":["string","null"]},"category":{"type":["string","null"]},"reason":{"type":["string","null"]}},"required":["provider","decision","risk","category","reason"]},"approval_rule":{"type":["string","null"]},"provider_ref":{"type":["string","null"]},"tx_hash":{"type":["string","null"]},"failure_reason":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","customer_id","asset","amount","network","beneficiary_id","destination_address","status","kp_fee_amount","screening","approval_rule","provider_ref","tx_hash","failure_reason","created_at"]}},"required":["success","status_code"]}}}},"400":{"description":"Invalid amount/address, or neither address nor beneficiary_id supplied"},"404":{"description":"Customer/wallet/beneficiary not found"},"422":{"description":"Beneficiary is not a crypto beneficiary, or conflicts with the supplied asset/address"}}},"get":{"tags":["Crypto Payouts"],"summary":"List a customer’s crypto payouts","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"asset":{"type":"string","enum":["BTC","ETH","USDT","USDC"]},"amount":{"type":"string"},"network":{"type":["string","null"]},"beneficiary_id":{"type":["string","null"],"format":"uuid"},"destination_address":{"type":"string"},"status":{"type":"string","enum":["initiated","pending_approval","approved","submitted","processing","settled","blocked","failed"]},"kp_fee_amount":{"type":"string"},"screening":{"type":"object","properties":{"provider":{"type":["string","null"]},"decision":{"type":["string","null"]},"risk":{"type":["string","null"]},"category":{"type":["string","null"]},"reason":{"type":["string","null"]}},"required":["provider","decision","risk","category","reason"]},"approval_rule":{"type":["string","null"]},"provider_ref":{"type":["string","null"]},"tx_hash":{"type":["string","null"]},"failure_reason":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","customer_id","asset","amount","network","beneficiary_id","destination_address","status","kp_fee_amount","screening","approval_rule","provider_ref","tx_hash","failure_reason","created_at"]}}},"required":["success","status_code"]}}}}}}},"/v1/partner/crypto-payouts":{"get":{"tags":["Crypto Payouts"],"summary":"List all crypto payouts in the programme","security":[{"partnerApiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"asset":{"type":"string","enum":["BTC","ETH","USDT","USDC"]},"amount":{"type":"string"},"network":{"type":["string","null"]},"beneficiary_id":{"type":["string","null"],"format":"uuid"},"destination_address":{"type":"string"},"status":{"type":"string","enum":["initiated","pending_approval","approved","submitted","processing","settled","blocked","failed"]},"kp_fee_amount":{"type":"string"},"screening":{"type":"object","properties":{"provider":{"type":["string","null"]},"decision":{"type":["string","null"]},"risk":{"type":["string","null"]},"category":{"type":["string","null"]},"reason":{"type":["string","null"]}},"required":["provider","decision","risk","category","reason"]},"approval_rule":{"type":["string","null"]},"provider_ref":{"type":["string","null"]},"tx_hash":{"type":["string","null"]},"failure_reason":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","customer_id","asset","amount","network","beneficiary_id","destination_address","status","kp_fee_amount","screening","approval_rule","provider_ref","tx_hash","failure_reason","created_at"]}}},"required":["success","status_code"]}}}}}}},"/v1/partner/usage":{"get":{"tags":["Metering"],"summary":"Usage summary (metered events) for the program","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"date-time"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","additionalProperties":{"type":"number"}}},"required":["success","status_code"]}}}}}}},"/v1/partner/billing/preview":{"get":{"tags":["Metering"],"summary":"Billing preview — metered usage priced by the KP price book","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"date-time"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["success","status_code"]}}}}}}},"/v1/partner/pnl":{"get":{"tags":["Metering"],"summary":"What the partner earned from their markup","description":"The programme’s OWN earnings: markup on payouts (per currency, minor units) and on settled conversions (per asset, decimal). Deliberately excludes KwiikPay’s revenue and provider cost — the first is what the partner PAID us, and the second is our cost base.","security":[{"partnerApiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"fiat":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"partner_revenue_minor":{"type":"integer"}},"required":["currency","partner_revenue_minor"]}},"conversion_fees":{"type":"array","items":{"type":"object","properties":{"asset":{"type":"string"},"partner_amount":{"type":"string"}},"required":["asset","partner_amount"]}}},"required":["fiat","conversion_fees"]}},"required":["success","status_code"]}}}}}}},"/v1/partner/invoices":{"get":{"tags":["Metering"],"summary":"List the program’s invoices","security":[{"partnerApiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["success","status_code"]}}}}}}},"/v1/partner/customers/{customerId}/crypto-wallets":{"post":{"tags":["Crypto"],"summary":"Open a crypto custody vault (per asset)","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"asset":{"type":"string","enum":["BTC","ETH","USDT","USDC"]}},"required":["asset"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"asset":{"type":"string","enum":["BTC","ETH","USDT","USDC"]},"provider":{"type":"string"},"network":{"type":"string"},"protocol":{"type":"string","enum":["native","ERC-20","TRC-20"]},"network_ref":{"type":["string","null"]},"deposit_address":{"type":["string","null"]},"status":{"type":"string","enum":["pending","active","frozen"]},"created_at":{"type":"string"},"balance":{"type":"string"},"available_balance":{"type":"string"},"reserved_balance":{"type":"string"}},"required":["id","customer_id","asset","provider","network","protocol","network_ref","deposit_address","status","created_at","balance","available_balance","reserved_balance"]}},"required":["success","status_code"]}}}},"404":{"description":"Customer not found"}}},"get":{"tags":["Crypto"],"summary":"List crypto custody vaults","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"asset":{"type":"string","enum":["BTC","ETH","USDT","USDC"]},"provider":{"type":"string"},"network":{"type":"string"},"protocol":{"type":"string","enum":["native","ERC-20","TRC-20"]},"network_ref":{"type":["string","null"]},"deposit_address":{"type":["string","null"]},"status":{"type":"string","enum":["pending","active","frozen"]},"created_at":{"type":"string"},"balance":{"type":"string"},"available_balance":{"type":"string"},"reserved_balance":{"type":"string"}},"required":["id","customer_id","asset","provider","network","protocol","network_ref","deposit_address","status","created_at","balance","available_balance","reserved_balance"]}}},"required":["success","status_code"]}}}}}}},"/v1/partner/customers/{customerId}/transactions":{"get":{"tags":["History"],"summary":"Customer transaction history (deposits, payouts, conversions) with fees","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["deposit","payout","conversion"]},"status":{"type":"string"},"source_asset":{"type":"string"},"source_amount":{"type":"string"},"target_asset":{"type":["string","null"]},"target_amount":{"type":["string","null"]},"fee_amount":{"type":"string"},"fee_asset":{"type":"string"},"partner_earning":{"type":"string"},"created_at":{"type":"string"},"detail":{"type":"string"}},"required":["id","type","status","source_asset","source_amount","target_asset","target_amount","fee_amount","fee_asset","partner_earning","created_at"]}}},"required":["success","status_code"]}}}}}}},"/v1/partner/customers/{customerId}/statement":{"get":{"tags":["History"],"summary":"Customer account statement for a period (history + fee summary)","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]},"generated_at":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["deposit","payout","conversion"]},"status":{"type":"string"},"source_asset":{"type":"string"},"source_amount":{"type":"string"},"target_asset":{"type":["string","null"]},"target_amount":{"type":["string","null"]},"fee_amount":{"type":"string"},"fee_asset":{"type":"string"},"partner_earning":{"type":"string"},"created_at":{"type":"string"},"detail":{"type":"string"}},"required":["id","type","status","source_asset","source_amount","target_asset","target_amount","fee_amount","fee_asset","partner_earning","created_at"]}},"summary":{"type":"object","properties":{"count":{"type":"number"},"by_type":{"type":"object","properties":{"deposit":{"type":"number"},"payout":{"type":"number"},"conversion":{"type":"number"}},"required":["deposit","payout","conversion"]},"fees":{"type":"object","additionalProperties":{"type":"string"}}},"required":["count","by_type","fees"]}},"required":["from","to","generated_at","items","summary"]}},"required":["success","status_code"]}}}}}}},"/v1/partner/rates":{"get":{"tags":["Conversions"],"summary":"Indicative rate — what a conversion would cost right now (read-only)","description":"Prices a conversion WITHOUT creating one: no conversion record, no ledger entry, no order with the provider. Use this for rate displays and tickers, and keep `POST /conversions` for one firm quote per actual intent.\n\n**The price is not held.** It is a look at the market this instant; only `POST /conversions` locks a rate you can approve.\n\nPriced through the same path as a firm quote, so the number here is the number you get — including the same minimum-size and fee rules. Pass `customer_id` to apply that customer's own markup; omit it for the programme rate. No KYC gate — a rate can be shown before a customer is verified.","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Source asset, e.g. GBP"},"required":true,"description":"Source asset, e.g. GBP","name":"from","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Target asset, e.g. USDC"},"required":true,"description":"Target asset, e.g. USDC","name":"to","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"description":"Amount of `from` to convert. Required — the provider prices by size."},"required":true,"description":"Amount of `from` to convert. Required — the provider prices by size.","name":"amount","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Price with this customer's markup override, if they have one."},"required":false,"description":"Price with this customer's markup override, if they have one.","name":"customer_id","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"source_asset":{"type":"string"},"target_asset":{"type":"string"},"source_amount":{"type":"number"},"target_amount":{"type":["number","null"],"description":"What the customer would receive, net of every fee below."},"rate":{"type":["number","null"],"description":"The raw provider rate, before fees."},"pair":{"type":"string"},"side":{"type":"string","enum":["buy","sell"]},"direction":{"type":"string","enum":["onramp","offramp","crypto_crypto","fiat_fiat"]},"kp_fee_bps":{"type":"number"},"kp_fee_amount":{"type":["number","null"]},"partner_fee_bps":{"type":"number"},"partner_fee_amount":{"type":["number","null"]},"provider_fee_amount":{"type":["number","null"]},"provider_fee_asset":{"type":["string","null"]}},"required":["source_asset","target_asset","source_amount","target_amount","rate","pair","side","direction","kp_fee_bps","kp_fee_amount","partner_fee_bps","partner_fee_amount","provider_fee_amount","provider_fee_asset"]}},"required":["success","status_code"]}}}},"404":{"description":"Customer not found (when customer_id is supplied)"},"422":{"description":"Unknown asset, same source/target, or below the minimum conversion size"}}}},"/v1/partner/customers/{customerId}/conversions":{"post":{"tags":["Conversions"],"summary":"Quote a conversion (fiat↔crypto / crypto↔crypto / fiat↔fiat) for a customer","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_asset":{"type":"string"},"target_asset":{"type":"string"},"source_amount":{"type":"number","exclusiveMinimum":0}},"required":["source_asset","target_asset","source_amount"]}}}},"responses":{"201":{"description":"Quoted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["onramp","offramp","crypto_crypto","fiat_fiat"]},"source_asset":{"type":"string"},"source_amount":{"type":"string"},"target_asset":{"type":"string"},"target_amount":{"type":["string","null"]},"pair":{"type":["string","null"]},"side":{"type":["string","null"]},"quote_rate":{"type":["string","null"]},"quote_expires_at":{"type":["string","null"]},"kp_fee_bps":{"type":"number"},"kp_fee_amount":{"type":["string","null"]},"partner_fee_bps":{"type":"number"},"partner_fee_amount":{"type":["string","null"]},"provider_fee_amount":{"type":["string","null"]},"provider_fee_asset":{"type":["string","null"]},"status":{"type":"string","enum":["quoted","approved","executing","settled","failed","cancelled","expired"]},"steps":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"status":{"type":"string"},"ref":{"type":"string"},"note":{"type":"string"},"at":{"type":"string"}},"required":["kind","status"]}},"failure_reason":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","customer_id","direction","source_asset","source_amount","target_asset","target_amount","pair","side","quote_rate","quote_expires_at","kp_fee_bps","kp_fee_amount","partner_fee_bps","partner_fee_amount","provider_fee_amount","provider_fee_asset","status","steps","failure_reason","created_at"]}},"required":["success","status_code"]}}}},"404":{"description":"Customer not found"},"422":{"description":"Unsupported pair / insufficient funds"}}},"get":{"tags":["Conversions"],"summary":"List a customer’s conversions","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"customerId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["onramp","offramp","crypto_crypto","fiat_fiat"]},"source_asset":{"type":"string"},"source_amount":{"type":"string"},"target_asset":{"type":"string"},"target_amount":{"type":["string","null"]},"pair":{"type":["string","null"]},"side":{"type":["string","null"]},"quote_rate":{"type":["string","null"]},"quote_expires_at":{"type":["string","null"]},"kp_fee_bps":{"type":"number"},"kp_fee_amount":{"type":["string","null"]},"partner_fee_bps":{"type":"number"},"partner_fee_amount":{"type":["string","null"]},"provider_fee_amount":{"type":["string","null"]},"provider_fee_asset":{"type":["string","null"]},"status":{"type":"string","enum":["quoted","approved","executing","settled","failed","cancelled","expired"]},"steps":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"status":{"type":"string"},"ref":{"type":"string"},"note":{"type":"string"},"at":{"type":"string"}},"required":["kind","status"]}},"failure_reason":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","customer_id","direction","source_asset","source_amount","target_asset","target_amount","pair","side","quote_rate","quote_expires_at","kp_fee_bps","kp_fee_amount","partner_fee_bps","partner_fee_amount","provider_fee_amount","provider_fee_asset","status","steps","failure_reason","created_at"]}}},"required":["success","status_code"]}}}}}}},"/v1/partner/conversions/{id}/approve":{"post":{"tags":["Conversions"],"summary":"Approve a quoted conversion → executes the cycle","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["onramp","offramp","crypto_crypto","fiat_fiat"]},"source_asset":{"type":"string"},"source_amount":{"type":"string"},"target_asset":{"type":"string"},"target_amount":{"type":["string","null"]},"pair":{"type":["string","null"]},"side":{"type":["string","null"]},"quote_rate":{"type":["string","null"]},"quote_expires_at":{"type":["string","null"]},"kp_fee_bps":{"type":"number"},"kp_fee_amount":{"type":["string","null"]},"partner_fee_bps":{"type":"number"},"partner_fee_amount":{"type":["string","null"]},"provider_fee_amount":{"type":["string","null"]},"provider_fee_asset":{"type":["string","null"]},"status":{"type":"string","enum":["quoted","approved","executing","settled","failed","cancelled","expired"]},"steps":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"status":{"type":"string"},"ref":{"type":"string"},"note":{"type":"string"},"at":{"type":"string"}},"required":["kind","status"]}},"failure_reason":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","customer_id","direction","source_asset","source_amount","target_asset","target_amount","pair","side","quote_rate","quote_expires_at","kp_fee_bps","kp_fee_amount","partner_fee_bps","partner_fee_amount","provider_fee_amount","provider_fee_asset","status","steps","failure_reason","created_at"]}},"required":["success","status_code"]}}}},"409":{"description":"Not quoted / expired"}}}},"/v1/partner/conversions/{id}/cancel":{"post":{"tags":["Conversions"],"summary":"Cancel a quoted conversion","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["onramp","offramp","crypto_crypto","fiat_fiat"]},"source_asset":{"type":"string"},"source_amount":{"type":"string"},"target_asset":{"type":"string"},"target_amount":{"type":["string","null"]},"pair":{"type":["string","null"]},"side":{"type":["string","null"]},"quote_rate":{"type":["string","null"]},"quote_expires_at":{"type":["string","null"]},"kp_fee_bps":{"type":"number"},"kp_fee_amount":{"type":["string","null"]},"partner_fee_bps":{"type":"number"},"partner_fee_amount":{"type":["string","null"]},"provider_fee_amount":{"type":["string","null"]},"provider_fee_asset":{"type":["string","null"]},"status":{"type":"string","enum":["quoted","approved","executing","settled","failed","cancelled","expired"]},"steps":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"status":{"type":"string"},"ref":{"type":"string"},"note":{"type":"string"},"at":{"type":"string"}},"required":["kind","status"]}},"failure_reason":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","customer_id","direction","source_asset","source_amount","target_asset","target_amount","pair","side","quote_rate","quote_expires_at","kp_fee_bps","kp_fee_amount","partner_fee_bps","partner_fee_amount","provider_fee_amount","provider_fee_asset","status","steps","failure_reason","created_at"]}},"required":["success","status_code"]}}}},"409":{"description":"Not cancellable"}}}},"/v1/partner/conversions/{id}":{"get":{"tags":["Conversions"],"summary":"Get a conversion","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["onramp","offramp","crypto_crypto","fiat_fiat"]},"source_asset":{"type":"string"},"source_amount":{"type":"string"},"target_asset":{"type":"string"},"target_amount":{"type":["string","null"]},"pair":{"type":["string","null"]},"side":{"type":["string","null"]},"quote_rate":{"type":["string","null"]},"quote_expires_at":{"type":["string","null"]},"kp_fee_bps":{"type":"number"},"kp_fee_amount":{"type":["string","null"]},"partner_fee_bps":{"type":"number"},"partner_fee_amount":{"type":["string","null"]},"provider_fee_amount":{"type":["string","null"]},"provider_fee_asset":{"type":["string","null"]},"status":{"type":"string","enum":["quoted","approved","executing","settled","failed","cancelled","expired"]},"steps":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"status":{"type":"string"},"ref":{"type":"string"},"note":{"type":"string"},"at":{"type":"string"}},"required":["kind","status"]}},"failure_reason":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","customer_id","direction","source_asset","source_amount","target_asset","target_amount","pair","side","quote_rate","quote_expires_at","kp_fee_bps","kp_fee_amount","partner_fee_bps","partner_fee_amount","provider_fee_amount","provider_fee_asset","status","steps","failure_reason","created_at"]}},"required":["success","status_code"]}}}},"404":{"description":"Not found"}}}},"/auth/signup":{"post":{"tags":["Auth"],"summary":"Create a programme + owner account (sends an email 2FA code)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"programme_name":{"type":"string","minLength":2},"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8},"name":{"type":"string"}},"required":["programme_name","email","password"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"next":{"type":"string","enum":["verify"]},"email":{"type":"string"}},"required":["next","email"]}},"required":["success","status_code"]}}}},"403":{"description":"Self-signup disabled"},"409":{"description":"Email taken"}}}},"/auth/login":{"post":{"tags":["Auth"],"summary":"Verify password, send an email 2FA code","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"next":{"type":"string","enum":["verify"]},"email":{"type":"string"}},"required":["next","email"]}},"required":["success","status_code"]}}}},"401":{"description":"Invalid credentials"}}}},"/auth/verify":{"post":{"tags":["Auth"],"summary":"Verify the email 2FA code → returns a session token","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"code":{"type":"string","minLength":6,"maxLength":6}},"required":["email","code"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":["string","null"]},"role":{"type":"string"}},"required":["id","email","name","role"]},"program":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"public_key":{"type":"string"}},"required":["id","name","public_key"]},"session_token":{"type":"string"},"expires_at":{"type":"string"}},"required":["user","program","session_token","expires_at"]}},"required":["success","status_code"]}}}},"401":{"description":"Invalid code"}}}},"/auth/session":{"get":{"tags":["Auth"],"summary":"Validate a session token (Authorization: Bearer <session_token>)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":["string","null"]},"role":{"type":"string"}},"required":["id","email","name","role"]},"program":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"public_key":{"type":"string"}},"required":["id","name","public_key"]}},"required":["user","program"]}},"required":["success","status_code"]}}}},"401":{"description":"No/invalid session"}}}},"/auth/logout":{"post":{"tags":["Auth"],"summary":"Invalidate the session","responses":{"200":{"description":"OK"}}}},"/auth/change-password":{"post":{"tags":["Auth"],"summary":"Change your password (Authorization: Bearer <session_token>)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"current_password":{"type":"string"},"new_password":{"type":"string","minLength":8}},"required":["current_password","new_password"]}}}},"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated"},"403":{"description":"Current password incorrect"}}}},"/auth/accept-invite":{"post":{"tags":["Auth"],"summary":"Accept a team invite: set name + password","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"name":{"type":"string"},"password":{"type":"string","minLength":8}},"required":["token","password"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"email":{"type":"string"}},"required":["email"]}},"required":["success","status_code"]}}}},"404":{"description":"Invalid invite"}}}},"/v1/partner/tickets":{"post":{"tags":["Support"],"summary":"Open a support ticket","security":[{"partnerApiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string","minLength":1,"maxLength":200},"module":{"type":"string","enum":["kyc_kyb","vibans","wallets","crypto","conversions","payouts","beneficiaries","pricing","webhooks","api_auth","other"]},"environment":{"type":"string","enum":["sandbox","production"],"default":"sandbox"},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"description":{"type":"string","minLength":1},"request_payload":{"type":"string"},"expected_result":{"type":"string"},"actual_result":{"type":"string"},"error_code":{"type":"string"},"customer_id":{"type":"string","format":"uuid"},"payout_id":{"type":"string","format":"uuid"},"conversion_id":{"type":"string","format":"uuid"},"created_by_email":{"type":"string","format":"email"}},"required":["subject","module","description"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string"},"program_id":{"type":"string"},"created_by_email":{"type":["string","null"]},"subject":{"type":"string"},"status":{"type":"string","enum":["open","triaging","in_progress","waiting_partner","resolved","closed"]},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"module":{"type":"string","enum":["kyc_kyb","vibans","wallets","crypto","conversions","payouts","beneficiaries","pricing","webhooks","api_auth","other"]},"environment":{"type":"string","enum":["sandbox","production"]},"description":{"type":"string"},"request_payload":{"type":["string","null"]},"expected_result":{"type":["string","null"]},"actual_result":{"type":["string","null"]},"error_code":{"type":["string","null"]},"customer_id":{"type":["string","null"]},"payout_id":{"type":["string","null"]},"conversion_id":{"type":["string","null"]},"assignee_staff_id":{"type":["string","null"]},"ai_status":{"type":"string","enum":["untriaged","triaged","pr_opened","needs_human"]},"linked_pr_url":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","program_id","created_by_email","subject","status","priority","module","environment","description","request_payload","expected_result","actual_result","error_code","customer_id","payout_id","conversion_id","assignee_staff_id","ai_status","linked_pr_url","created_at","updated_at"]}},"required":["success","status_code"]}}}}}},"get":{"tags":["Support"],"summary":"List your support tickets","security":[{"partnerApiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"program_id":{"type":"string"},"created_by_email":{"type":["string","null"]},"subject":{"type":"string"},"status":{"type":"string","enum":["open","triaging","in_progress","waiting_partner","resolved","closed"]},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"module":{"type":"string","enum":["kyc_kyb","vibans","wallets","crypto","conversions","payouts","beneficiaries","pricing","webhooks","api_auth","other"]},"environment":{"type":"string","enum":["sandbox","production"]},"description":{"type":"string"},"request_payload":{"type":["string","null"]},"expected_result":{"type":["string","null"]},"actual_result":{"type":["string","null"]},"error_code":{"type":["string","null"]},"customer_id":{"type":["string","null"]},"payout_id":{"type":["string","null"]},"conversion_id":{"type":["string","null"]},"assignee_staff_id":{"type":["string","null"]},"ai_status":{"type":"string","enum":["untriaged","triaged","pr_opened","needs_human"]},"linked_pr_url":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","program_id","created_by_email","subject","status","priority","module","environment","description","request_payload","expected_result","actual_result","error_code","customer_id","payout_id","conversion_id","assignee_staff_id","ai_status","linked_pr_url","created_at","updated_at"]}}},"required":["success","status_code"]}}}}}}},"/v1/partner/tickets/{id}":{"get":{"tags":["Support"],"summary":"Ticket detail + conversation","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"ticket":{"type":"object","properties":{"id":{"type":"string"},"program_id":{"type":"string"},"created_by_email":{"type":["string","null"]},"subject":{"type":"string"},"status":{"type":"string","enum":["open","triaging","in_progress","waiting_partner","resolved","closed"]},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"module":{"type":"string","enum":["kyc_kyb","vibans","wallets","crypto","conversions","payouts","beneficiaries","pricing","webhooks","api_auth","other"]},"environment":{"type":"string","enum":["sandbox","production"]},"description":{"type":"string"},"request_payload":{"type":["string","null"]},"expected_result":{"type":["string","null"]},"actual_result":{"type":["string","null"]},"error_code":{"type":["string","null"]},"customer_id":{"type":["string","null"]},"payout_id":{"type":["string","null"]},"conversion_id":{"type":["string","null"]},"assignee_staff_id":{"type":["string","null"]},"ai_status":{"type":"string","enum":["untriaged","triaged","pr_opened","needs_human"]},"linked_pr_url":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","program_id","created_by_email","subject","status","priority","module","environment","description","request_payload","expected_result","actual_result","error_code","customer_id","payout_id","conversion_id","assignee_staff_id","ai_status","linked_pr_url","created_at","updated_at"]},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"author_type":{"type":"string","enum":["partner","kp","ai"]},"author_name":{"type":["string","null"]},"body":{"type":"string"},"internal":{"type":"boolean"},"created_at":{"type":"string"}},"required":["id","author_type","author_name","body","internal","created_at"]}}},"required":["ticket","messages"]}},"required":["success","status_code"]}}}},"404":{"description":"Not found"}}}},"/v1/partner/tickets/{id}/messages":{"post":{"tags":["Support"],"summary":"Reply to a ticket","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1},"author_name":{"type":"string"}},"required":["body"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string"},"author_type":{"type":"string","enum":["partner","kp","ai"]},"author_name":{"type":["string","null"]},"body":{"type":"string"},"internal":{"type":"boolean"},"created_at":{"type":"string"}},"required":["id","author_type","author_name","body","internal","created_at"]}},"required":["success","status_code"]}}}},"404":{"description":"Not found"}}}},"/v1/partner/webhooks/endpoint":{"get":{"tags":["Webhooks"],"summary":"Get the webhook endpoint config + available event types","security":[{"partnerApiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"url":{"type":["string","null"]},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"secret":{"type":"string"},"available_events":{"type":"array","items":{"type":"string"}}},"required":["url","events","active","available_events"]}},"required":["success","status_code"]}}}}}},"put":{"tags":["Webhooks"],"summary":"Set the webhook endpoint (secret returned once on create/rotate)","security":[{"partnerApiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["verification.updated","account.opened","account.updated","deposit.received","payout.settled","crypto_payout.settled","crypto_payout.blocked","conversion.settled","monitoring.alert"]}},"active":{"type":"boolean"},"rotate_secret":{"type":"boolean"}},"required":["url"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"url":{"type":["string","null"]},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"secret":{"type":"string"}},"required":["url","events","active"]}},"required":["success","status_code"]}}}},"422":{"description":"Webhook URL rejected (not a public http(s) address)"}}}},"/v1/partner/webhooks/deliveries":{"get":{"tags":["Webhooks"],"summary":"Webhook delivery log (events KP sent to this programme)","security":[{"partnerApiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"event":{"type":"string"},"status":{"type":"string","enum":["pending","success","failed"]},"response_status":{"type":["number","null"]},"attempts":{"type":"number"},"error":{"type":["string","null"]},"payload":{},"created_at":{"type":"string"}},"required":["id","event","status","response_status","attempts","error","created_at"]}}},"required":["success","status_code"]}}}}}}},"/v1/partner/webhooks/deliveries/{id}/redeliver":{"post":{"tags":["Webhooks"],"summary":"Re-attempt a webhook delivery","security":[{"partnerApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string"},"event":{"type":"string"},"status":{"type":"string","enum":["pending","success","failed"]},"response_status":{"type":["number","null"]},"attempts":{"type":"number"},"error":{"type":["string","null"]},"payload":{},"created_at":{"type":"string"}},"required":["id","event","status","response_status","attempts","error","created_at"]}},"required":["success","status_code"]}}}},"404":{"description":"Not found"}}}},"/v1/partner/team":{"get":{"tags":["Team"],"summary":"List the programme’s team (users)","security":[{"partnerApiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"number"},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":["string","null"]},"role":{"type":"string","enum":["owner","admin","member"]},"status":{"type":"string","enum":["active","invited","disabled"]},"created_at":{"type":"string"}},"required":["id","email","name","role","status","created_at"]}}},"required":["success","status_code"]}}}}}}}},"webhooks":{}}