{ "openapi": "3.0.3", "info": { "title": "MiCash Integrator Beneficiary API", "version": "1.0.0", "description": "Project-isolated registration, wallet and cashout. Configure host, sponsor companyUuid and project apiKey only. Project ownership is derived from the authenticated key. No application header is required. Existing shared sponsor keys remain supported; legacy ownership is not guessed. Reviewed 2026-10-15. MiCash charging defaults off in the fee-policy release; localFee is zero for new quotes while disabled, provider fees remain separate, and previous quotes retain their terms. Existing GMP uses application code GMT; linking never transfers existing pocket balances. Fee update 2026-10-20: incoming donations have no MiCash deduction even when enabled; customer funding currently has no separate fee. Bank quotes include quote.breakdown with PascalCase fee and debit/net fields. See /docs/fees-and-amounts for caps, thresholds, exact amount models and dev tests." }, "servers": [ { "url": "https://localhost:44372", "description": "Local development; configure your MiCash HTTPS host for other environments." } ], "paths": { "/micash/{companyUuid}/integrator-wallet/customer-fundings": { "post": { "operationId": "fundProjectCustomer", "summary": "21 Fund a linked customer from project funds", "description": "Sends real money when customer funding is explicitly enabled by Super Admin. Only this project confirmed funds and ACTIVE customer associations can be used. No maturation wait applies to customer funding. No customer PIN/session is needed; restrict this action to your own authenticated project administrators on your backend. Generate and save one UUID fundingRequestId per intended transfer BEFORE submitting. Reuse that exact ID and body after an uncertain HTTP response; read status first and never create a replacement until reconciled. Choose Donation, Payment or Subscription; payer, payee and category pocket are resolved by MiCash. Confirm amount and customer before sending. A success envelope can contain PROCESSING or REQUIRES_REVIEW, which do not prove delivery. SUBMITTED means confirmed provider acceptance and local pocket credit.", "parameters": [ { "name": "companyUuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "IntegratorKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "requestId", "onboardingId", "amount", "category" ], "properties": { "requestId": { "type": "string", "format": "uuid" }, "onboardingId": { "type": "string", "format": "uuid" }, "amount": { "type": "number", "minimum": 0.01, "maximum": 999999999, "multipleOf": 0.01 }, "category": { "type": "string", "enum": [ "Donation", "Payment", "Subscription" ] } } } } } }, "responses": { "200": { "description": "Recorded funding; inspect status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "funding": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "onboardingId": { "type": "string", "format": "uuid" }, "amount": { "type": "number" }, "currency": { "type": "string", "enum": [ "ZAR" ] }, "category": { "type": "string", "enum": [ "Donation", "Payment", "Subscription" ] }, "status": { "type": "string", "enum": [ "PROCESSING", "SUBMITTED", "REQUIRES_REVIEW" ] }, "providerReference": { "type": "string" } } } } }, "example": { "success": true, "funding": { "requestId": "00000000-0000-4000-8000-000000000021", "onboardingId": "00000000-0000-4000-8000-000000000001", "amount": 10, "currency": "ZAR", "category": "Donation", "status": "SUBMITTED", "providerReference": "MW-00000000000040008000000000000021" }, "message": "Provider accepted the transfer and the customer pocket was credited." } } } }, "202": { "description": "Durably reserved or uncertain transfer. Reconcile the original ID; no replacement.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "funding": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "onboardingId": { "type": "string", "format": "uuid" }, "amount": { "type": "number" }, "currency": { "type": "string", "enum": [ "ZAR" ] }, "category": { "type": "string", "enum": [ "Donation", "Payment", "Subscription" ] }, "status": { "type": "string", "enum": [ "PROCESSING", "SUBMITTED", "REQUIRES_REVIEW" ] }, "providerReference": { "type": "string" } } } } } } } }, "400": { "description": "Invalid amount, category or UUID." }, "401": { "description": "Invalid project key/company." }, "403": { "description": "HTTPS required, project key required, funding disabled or project access changed." }, "404": { "description": "No active owning customer link or eligible project source pocket." }, "409": { "description": "Request ID payload conflict or insufficient confirmed project funds." }, "503": { "description": "Funding schema, source/provider balance or operation unavailable. Inspect saved status before any retry." } } } }, "/micash/{companyUuid}/integrator-wallet/customer-fundings/{requestId}": { "get": { "operationId": "getProjectCustomerFunding", "summary": "Read durable customer funding status", "description": "Project-owned status read with no provider call; customer session not required. A success envelope does not prove delivery: inspect funding.status.", "parameters": [ { "name": "companyUuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "IntegratorKey": [] } ], "responses": { "200": { "description": "Recorded funding; inspect status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "funding": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "onboardingId": { "type": "string", "format": "uuid" }, "amount": { "type": "number" }, "currency": { "type": "string", "enum": [ "ZAR" ] }, "category": { "type": "string", "enum": [ "Donation", "Payment", "Subscription" ] }, "status": { "type": "string", "enum": [ "PROCESSING", "SUBMITTED", "REQUIRES_REVIEW" ] }, "providerReference": { "type": "string" } } } } }, "example": { "success": true, "funding": { "requestId": "00000000-0000-4000-8000-000000000021", "onboardingId": "00000000-0000-4000-8000-000000000001", "amount": 10, "currency": "ZAR", "category": "Donation", "status": "SUBMITTED", "providerReference": "MW-00000000000040008000000000000021" }, "message": "Provider accepted the transfer and the customer pocket was credited." } } } }, "202": { "description": "Durably reserved or uncertain transfer. Reconcile the original ID; no replacement.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "funding": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "onboardingId": { "type": "string", "format": "uuid" }, "amount": { "type": "number" }, "currency": { "type": "string", "enum": [ "ZAR" ] }, "category": { "type": "string", "enum": [ "Donation", "Payment", "Subscription" ] }, "status": { "type": "string", "enum": [ "PROCESSING", "SUBMITTED", "REQUIRES_REVIEW" ] }, "providerReference": { "type": "string" } } } } } } } }, "400": { "description": "Invalid amount, category or UUID." }, "401": { "description": "Invalid project key/company." }, "403": { "description": "HTTPS required, project key required, funding disabled or project access changed." }, "404": { "description": "No active owning customer link or eligible project source pocket." }, "409": { "description": "Request ID payload conflict or insufficient confirmed project funds." }, "503": { "description": "Funding schema, source/provider balance or operation unavailable. Inspect saved status before any retry." } } } }, "/micash/{companyUuid}/integrator-wallet": { "get": { "operationId": "getProjectFundsBalance", "summary": "Read the project own funds held under its sponsor", "description": "Read the authenticated project own collected funds held under its sponsor, for example BiggPull under LEO. Use the project apiKey and matching sponsor companyUuid. No onboardingId, customer PIN or X-Wallet-Session is needed. The key derives the project scope; do not substitute the shared LEO key. This is a read-only allocation/settlement summary, not the sponsor entire provider balance or a customer wallet balance. availableForWithdrawal is matured collections less pending and approved/paid withdrawals. Example values are illustrative, not a verified account balance. availableForCustomerFunding uses confirmed collections without maturity, less payout holds and funding reservations. availableForWithdrawal retains payout maturity and also deducts funding reservations. Balance correction: balanceBasis=PROJECT_POCKETS_V1 identifies availability capped by actual project merchant category-pocket balances, after payout holds. Gross collections are historical, not spendable funds. R4 collected with a current Donation pocket of R3.95 allows at most R3.95 before further reservations. Customer funding does not wait for maturation.", "security": [ { "IntegratorKey": [] } ], "parameters": [ { "name": "companyUuid", "in": "path", "required": true, "description": "Sponsor company UUID from the same approved project configuration.", "schema": { "type": "string", "format": "uuid" } }, { "name": "siteName", "in": "query", "required": false, "description": "Legacy site selector. Omit for a project-bound key; cannot override its project identity.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Read-only project allocation summary; no provider account balance lookup or financial action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "siteName": { "type": "string" }, "responsibleMerchant": { "type": "string" }, "currency": { "type": "string", "enum": [ "ZAR" ] }, "grossCollected": { "type": "number", "format": "decimal" }, "pendingMaturation": { "type": "number", "format": "decimal" }, "pendingWithdrawals": { "type": "number", "format": "decimal" }, "paidOrApprovedWithdrawals": { "type": "number", "format": "decimal" }, "availableForWithdrawal": { "type": "number", "format": "decimal" }, "pockets": { "type": "array", "items": { "type": "object", "properties": { "PocketName": { "type": "string" }, "GrossCollected": { "type": "number", "format": "decimal" }, "MaturedCollected": { "type": "number", "format": "decimal" }, "PendingMaturation": { "type": "number", "format": "decimal" } } } }, "customerFundingHeld": { "type": "number", "format": "decimal" }, "availableForCustomerFunding": { "type": "number", "format": "decimal", "description": "Remaining confirmed project budget capped by actual project merchant category-pocket balances after payout holds. No maturation wait. Does not promise provider liquidity." }, "balanceBasis": { "type": "string", "enum": [ "PROJECT_POCKETS_V1" ] }, "projectWalletBalance": { "type": "number", "format": "decimal", "description": "Current local balances of the owning project merchant category pockets only; excludes LEO main funds, other projects and customer balances." }, "fundingCategories": { "type": "array", "items": { "type": "object", "properties": { "Category": { "type": "string", "enum": [ "Donation", "Payment", "Subscription" ] }, "Balance": { "type": "number", "format": "decimal" }, "AvailableForCustomerFunding": { "type": "number", "format": "decimal" } } } } } }, "example": { "success": true, "siteName": "thebiggpull", "responsibleMerchant": "LEO DEVELOPMENT GROUP", "currency": "ZAR", "grossCollected": 100, "pendingMaturation": 0, "pendingWithdrawals": 0, "paidOrApprovedWithdrawals": 0, "availableForWithdrawal": 90, "pockets": [], "customerFundingHeld": 10, "availableForCustomerFunding": 90 } } } }, "401": { "description": "Invalid or unauthorized integrator key/company binding." }, "503": { "description": "Integrator wallet storage schema is not configured." } } } }, "/api/v1/integrator/onboardings": { "post": { "operationId": "createOnboarding", "summary": "Create onboarding with an API-generated registration reference", "security": [ { "IntegratorKey": [] } ], "responses": { "200": { "description": "Controlled successful response; inspect status/test-data flags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "202": { "description": "Controlled successful response; inspect status/test-data flags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "410": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOnboarding" } } } }, "parameters": [ { "name": "companyUuid", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Merchant UUID matching the integrator secret." } ] } }, "/api/v1/integrator/onboardings/{id}": { "get": { "operationId": "getOnboarding", "summary": "Read owned onboarding status", "security": [ { "IntegratorKey": [] } ], "responses": { "200": { "description": "Controlled successful response; inspect status/test-data flags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "410": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyUuid", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Merchant UUID matching the integrator secret." } ] } }, "/api/v1/integrator/onboardings/by-reference": { "get": { "operationId": "getOnboardingByReference", "summary": "Resolve saved reference", "security": [ { "IntegratorKey": [] } ], "responses": { "200": { "description": "Controlled successful response; inspect status/test-data flags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "410": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "parameters": [ { "name": "externalReference", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "companyUuid", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Merchant UUID matching the integrator secret." } ] } }, "/api/v1/integrator/onboardings/{id}/otp-verification": { "post": { "operationId": "verifyRegistrationOtp", "summary": "Verify registration OTP", "security": [ { "IntegratorKey": [] } ], "responses": { "200": { "description": "Controlled successful response; inspect status/test-data flags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "410": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyUuid", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Merchant UUID matching the integrator secret." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationOtp" } } } } } }, "/api/v1/integrator/onboardings/{id}/profile-validation": { "post": { "operationId": "validateProfile", "summary": "Validate locally without provider write", "security": [ { "IntegratorKey": [] } ], "responses": { "200": { "description": "Controlled successful response; inspect status/test-data flags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "410": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyUuid", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Merchant UUID matching the integrator secret." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } } } }, "/api/v1/integrator/onboardings/{id}/profile": { "post": { "operationId": "createProfile", "summary": "Create provider profile once; separate PIN setup", "security": [ { "IntegratorKey": [] } ], "responses": { "200": { "description": "Controlled successful response; inspect status/test-data flags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "201": { "description": "Controlled successful response; inspect status/test-data flags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "410": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyUuid", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Merchant UUID matching the integrator secret." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } } } }, "/api/v1/integrator/onboardings/{id}/wallet-pin/otp": { "post": { "operationId": "requestPinOtp", "summary": "Request separate PIN OTP; no body", "security": [ { "IntegratorKey": [] } ], "responses": { "202": { "description": "Controlled successful response; inspect status/test-data flags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "410": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyUuid", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Merchant UUID matching the integrator secret." } ] } }, "/api/v1/integrator/onboardings/{id}/wallet-pin": { "post": { "operationId": "setWalletPin", "summary": "Set PIN using PIN OTP", "security": [ { "IntegratorKey": [] } ], "responses": { "200": { "description": "Controlled successful response; inspect status/test-data flags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "410": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyUuid", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Merchant UUID matching the integrator secret." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPin" } } } } } }, "/api/v1/integrator/onboardings/{id}/wallet-sessions": { "post": { "operationId": "openWalletSession", "summary": "Authenticate customer and issue opaque session", "security": [ { "IntegratorKey": [] } ], "responses": { "201": { "description": "Controlled successful response; inspect status/test-data flags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletEnvelope" } } } }, "400": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletEnvelope" } } } }, "401": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletEnvelope" } } } }, "403": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletEnvelope" } } } }, "404": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletEnvelope" } } } }, "409": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletEnvelope" } } } }, "410": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletEnvelope" } } } }, "503": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyUuid", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Merchant UUID matching the integrator secret." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Login" } } } } } }, "/api/v1/integrator/onboardings/{id}/wallet": { "get": { "operationId": "getWalletBalance", "summary": "Read balance; test data cannot activate wallet", "security": [ { "IntegratorKey": [], "WalletSession": [] } ], "responses": { "200": { "description": "Controlled successful response; inspect status/test-data flags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletEnvelope" } } } }, "400": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletEnvelope" } } } }, "401": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletEnvelope" } } } }, "403": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletEnvelope" } } } }, "404": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletEnvelope" } } } }, "409": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletEnvelope" } } } }, "410": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletEnvelope" } } } }, "503": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyUuid", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Merchant UUID matching the integrator secret." } ] } }, "/api/v1/integrator/onboardings/{id}/resume": { "post": { "operationId": "resumeOnboarding", "summary": "Resume same reference; no blind profile recreation", "security": [ { "IntegratorKey": [] } ], "responses": { "200": { "description": "Controlled successful response; inspect status/test-data flags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "202": { "description": "Controlled successful response; inspect status/test-data flags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "410": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyUuid", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Merchant UUID matching the integrator secret." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resume" } } } } } }, "/api/v1/integrator/onboardings/{id}/profile-link": { "post": { "operationId": "linkExistingProfile", "summary": "Authenticate and link confirmed existing profile", "security": [ { "IntegratorKey": [] } ], "responses": { "200": { "description": "Controlled successful response; inspect status/test-data flags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "410": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "Controlled error. Follow recovery guidance; do not blindly retry writes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyUuid", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Merchant UUID matching the integrator secret." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } } } }, "/api/v1/integrator/onboardings/{id}/bank-cashout-quotes": { "post": { "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutQuote" } } } }, "security": [ { "WalletSession": [], "IntegratorKey": [] } ], "responses": { "200": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "202": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "400": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "401": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "403": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "404": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "409": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "410": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "503": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } } }, "operationId": "quoteBankCashout", "summary": "Quote existing EFT bank cashout; no money movement", "parameters": [ { "required": true, "name": "id", "schema": { "format": "uuid", "type": "string" }, "in": "path" }, { "name": "companyUuid", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Merchant UUID matching the integrator secret." } ] } }, "/api/v1/integrator/onboardings/{id}/bank-cashouts": { "post": { "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutSubmit" } } } }, "security": [ { "WalletSession": [], "IntegratorKey": [] } ], "responses": { "200": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "202": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "400": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "401": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "403": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "404": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "409": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "410": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "503": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } } }, "operationId": "submitBankCashout", "summary": "Submit customer-confirmed cashout once; SUBMITTED does not mean settled", "parameters": [ { "required": true, "name": "id", "schema": { "format": "uuid", "type": "string" }, "in": "path" }, { "name": "companyUuid", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Merchant UUID matching the integrator secret." } ] } }, "/api/v1/integrator/onboardings/{id}/bank-cashouts/by-reference": { "get": { "security": [ { "IntegratorKey": [] } ], "responses": { "200": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "202": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "400": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "401": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "403": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "404": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "409": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "410": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } }, "503": { "description": "Controlled result; inspect withdrawal.status. Reconcile uncertain writes, never retry with a new reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashoutEnvelope" } } } } }, "operationId": "getBankCashout", "summary": "Read durable owned withdrawal status without provider calls", "parameters": [ { "required": true, "name": "id", "schema": { "format": "uuid", "type": "string" }, "in": "path" }, { "required": true, "name": "externalReference", "schema": { "type": "string", "maxLength": 120 }, "in": "query" }, { "name": "companyUuid", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Merchant UUID matching the integrator secret." } ] } }, "/api/v1/integrator/onboardings/{id}/unlink": { "post": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Controlled unlink result. UNLINKED revokes integrator access; financial records and provider account remain." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Controlled unlink result. UNLINKED revokes integrator access; financial records and provider account remain." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Controlled unlink result. UNLINKED revokes integrator access; financial records and provider account remain." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Controlled unlink result. UNLINKED revokes integrator access; financial records and provider account remain." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Controlled unlink result. UNLINKED revokes integrator access; financial records and provider account remain." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Controlled unlink result. UNLINKED revokes integrator access; financial records and provider account remain." } }, "security": [ { "IntegratorKey": [] } ], "summary": "Revoke onboarding access without deleting provider account or financial history", "operationId": "unlinkBeneficiary", "parameters": [ { "required": true, "schema": { "format": "uuid", "type": "string" }, "name": "id", "in": "path" }, { "name": "companyUuid", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Merchant UUID matching the integrator secret." } ] } }, "/api/v1/integrator/wallets": { "get": { "summary": "List linked wallets for authenticated integrator and merchant", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletListEnvelope" } } }, "description": "Controlled merchant-scoped wallet metadata; no live balance or provider identifiers." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletListEnvelope" } } }, "description": "Controlled merchant-scoped wallet metadata; no live balance or provider identifiers." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletListEnvelope" } } }, "description": "Controlled merchant-scoped wallet metadata; no live balance or provider identifiers." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletListEnvelope" } } }, "description": "Controlled merchant-scoped wallet metadata; no live balance or provider identifiers." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletListEnvelope" } } }, "description": "Controlled merchant-scoped wallet metadata; no live balance or provider identifiers." } }, "security": [ { "IntegratorKey": [] } ], "parameters": [ { "name": "page", "schema": { "maximum": 1000000, "minimum": 1, "type": "integer", "default": 1 }, "in": "query" }, { "name": "pageSize", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "default": 25 }, "in": "query" }, { "name": "companyUuid", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Merchant UUID matching the integrator secret." } ], "operationId": "listMerchantWallets" } } }, "components": { "securitySchemes": { "IntegratorKey": { "type": "apiKey", "in": "header", "name": "X-Integrator-Key", "description": "Approved project IntegratorSecrets.Secret_key copied from Super Admin, paired with its sponsor companyUuid. Project ownership is selected by this key. Existing shared sponsor keys retain their existing scope; no separate onboarding key is required." }, "WalletSession": { "type": "apiKey", "in": "header", "name": "X-Wallet-Session" } }, "schemas": { "CreateOnboarding": { "type": "object", "properties": { "identityNumber": { "type": "string" }, "firstNames": { "type": "string" }, "surname": { "type": "string" }, "email": { "type": "string", "format": "email" }, "mobileNumber": { "type": "string", "pattern": "^\\+27[0-9]{9}$" }, "externalReference": { "type": "string", "description": "Optional. When omitted, the API generates a registration reference and returns it in onboarding.externalReference. Save the returned reference for recovery and retries.", "maxLength": 120 } }, "required": [ "mobileNumber" ] }, "Identity": { "type": "object", "properties": { "identityNumber": { "type": "string", "pattern": "^[0-9]{13}$" }, "firstNames": { "type": "string", "maxLength": 50 }, "surname": { "type": "string", "maxLength": 50 }, "genderType": { "type": "string", "enum": [ "MALE", "FEMALE" ] }, "countryOfBirth": { "type": "string", "pattern": "^[A-Z]{2}$" }, "dateOfBirth": { "type": "string", "format": "date" }, "photo": { "type": "string" } }, "required": [ "identityNumber", "firstNames", "surname", "genderType", "countryOfBirth", "dateOfBirth" ] }, "Passport": { "type": "object", "properties": { "passportNumber": { "type": "string", "maxLength": 20 }, "firstNames": { "type": "string", "maxLength": 50 }, "surname": { "type": "string", "maxLength": 50 }, "genderType": { "type": "string", "enum": [ "MALE", "FEMALE" ] }, "countryOfIssue": { "type": "string", "pattern": "^[A-Z]{2}$" }, "countryOfCitizenship": { "type": "string", "pattern": "^[A-Z]{2}$" }, "dateOfBirth": { "type": "string", "format": "date" }, "dateOfIssue": { "type": "string", "format": "date" }, "dateOfExpiry": { "type": "string", "format": "date" }, "photo": { "type": "string" } }, "required": [ "passportNumber", "firstNames", "surname", "genderType", "countryOfIssue", "countryOfCitizenship", "dateOfBirth", "dateOfIssue", "dateOfExpiry", "photo" ] }, "Profile": { "type": "object", "properties": { "displayName": { "type": "string", "maxLength": 50 }, "email": { "type": "string", "format": "email", "maxLength": 80 }, "photo": { "type": "string", "description": "Actual single-line base64 JPEG/PNG selfie data URL." }, "identity": { "$ref": "#/components/schemas/Identity" }, "passport": { "$ref": "#/components/schemas/Passport" } }, "required": [ "displayName", "photo" ], "oneOf": [ { "required": [ "identity" ], "not": { "required": [ "passport" ] } }, { "required": [ "passport" ], "not": { "required": [ "identity" ] } } ] }, "RegistrationOtp": { "type": "object", "properties": { "otp": { "type": "string", "pattern": "^[0-9]{5}$", "writeOnly": true } }, "required": [ "otp" ] }, "SetPin": { "type": "object", "properties": { "otp": { "type": "string", "pattern": "^[0-9]{5}$", "writeOnly": true }, "pin": { "type": "string", "pattern": "^[0-9]{4,5}$", "writeOnly": true, "description": "Customer PIN; pass unchanged. Provider environment determines supported length." } }, "required": [ "otp", "pin" ] }, "Login": { "type": "object", "properties": { "pin": { "type": "string", "pattern": "^[0-9]{4,5}$", "writeOnly": true, "description": "Customer PIN; pass unchanged. Provider environment determines supported length." }, "packageName": { "type": "string", "maxLength": 160, "description": "Optional. When omitted or blank, MiCash uses its configured provider package (default com.micash.app). Existing supplied values remain supported." } }, "required": [ "pin" ] }, "Resume": { "type": "object", "properties": { "mobileNumber": { "type": "string", "pattern": "^\\+27[0-9]{9}$" } }, "required": [ "mobileNumber" ] }, "Link": { "type": "object", "properties": { "mobileNumber": { "type": "string", "pattern": "^\\+27[0-9]{9}$" }, "pin": { "type": "string", "pattern": "^[0-9]{4,5}$", "writeOnly": true, "description": "Customer PIN; pass unchanged. Provider environment determines supported length." }, "packageName": { "type": "string", "maxLength": 160, "description": "Optional. When omitted or blank, MiCash uses its configured provider package (default com.micash.app). Existing supplied values remain supported." } }, "required": [ "mobileNumber", "pin" ] }, "Onboarding": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalReference": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "RESUMING", "OTP_REQUIRED", "OTP_VERIFIED", "PROFILE_CREATED", "COMPLETING", "ACTIVE", "COMPLETION_REQUIRES_REVIEW", "EXISTING_PROFILE_REQUIRES_LINKING", "CHIPS_UNAVAILABLE", "OTP_RESULT_UNCONFIRMED", "REGISTRATION_RESULT_UNCONFIRMED", "UNLINKED" ] }, "merchant": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [] }, "beneficiaryReference": { "type": "integer", "nullable": true, "description": "Internal numeric association reference. This is not the customer's canonical identity." }, "customer": { "type": "object", "nullable": true, "description": "Present only after a verified PROFILE_CREATED or ACTIVE association. Persist only for the authenticated customer completing this onboarding.", "properties": { "eId": { "type": "string", "description": "Canonical MiCash customer identifier." }, "profileUuid": { "type": "string", "format": "uuid" }, "accountUuid": { "type": "string", "format": "uuid" } }, "required": [ "eId", "profileUuid", "accountUuid" ] }, "wallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer" }, "status": { "type": "string", "enum": [ "ACTIVE" ] } } }, "beneficiaryUrl": { "type": "string", "nullable": true, "description": "Legacy hosted flow only; API-native apps do not redirect." } }, "required": [ "id", "externalReference", "status" ] }, "Envelope": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string", "nullable": true }, "invalidField": { "type": "string", "nullable": true }, "failureStage": { "type": "string", "nullable": true }, "providerHttpStatus": { "type": "integer", "nullable": true }, "providerCode": { "type": "string", "nullable": true }, "onboarding": { "$ref": "#/components/schemas/Onboarding", "nullable": true } }, "required": [ "success" ] }, "WalletEnvelope": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string", "nullable": true }, "failureStage": { "type": "string", "nullable": true }, "providerHttpStatus": { "type": "integer", "nullable": true }, "providerCode": { "type": "string", "nullable": true }, "walletSession": { "type": "string", "nullable": true, "description": "Opaque secret retained on your backend; expires in 30 minutes and on restart." }, "expiresAt": { "type": "string", "nullable": true, "description": "Legacy ASP.NET MVC JSON date serialization; use as returned." }, "wallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "nullable": true }, "availableBalance": { "type": "number" }, "currency": { "type": "string", "enum": [ "ZAR" ] }, "isTestData": { "type": "boolean" } } } }, "required": [ "success" ] }, "CashoutEnvelope": { "properties": { "invalidField": { "type": "string", "nullable": true }, "quote": { "properties": { "amount": { "type": "number" }, "bankAmount": { "type": "number" }, "id": { "format": "uuid", "type": "string" }, "currency": { "type": "string", "enum": [ "ZAR" ] }, "localFee": { "type": "number" }, "providerFee": { "type": "number" }, "expiresAt": { "description": "MVC JSON date; five-minute expiry.", "type": "string" }, "breakdown": { "$ref": "#/components/schemas/FeeBreakdown" } }, "type": "object", "nullable": true }, "error": { "type": "string", "nullable": true }, "withdrawal": { "properties": { "id": { "format": "uuid", "type": "string" }, "reference": { "type": "string" }, "currency": { "type": "string", "enum": [ "ZAR" ] }, "amount": { "type": "number" }, "providerFee": { "type": "number" }, "localFee": { "type": "number" }, "status": { "type": "string", "enum": [ "PROCESSING", "FEE_PROCESSING", "SUBMITTED", "REQUIRES_REVIEW" ] }, "externalReference": { "type": "string" }, "bankAmount": { "type": "number" } }, "type": "object", "nullable": true }, "success": { "type": "boolean" } }, "type": "object" }, "CashoutSubmit": { "properties": { "externalReference": { "description": "Stable unique withdrawal reference, separate from onboarding reference. Never change to retry.", "type": "string", "maxLength": 120 }, "quoteId": { "format": "uuid", "type": "string" } }, "type": "object", "required": [ "quoteId", "externalReference" ] }, "CashoutQuote": { "properties": { "branchCode": { "type": "string", "pattern": "^[0-9]{6}$" }, "amount": { "multipleOf": 0.01, "minimum": 0, "type": "number", "description": "Total ZAR debit budget including provider and MiCash fees; bankAmount is lower.", "exclusiveMinimum": true }, "accountNumber": { "pattern": "^[0-9]{4,20}$", "type": "string", "writeOnly": true }, "accountName": { "type": "string", "maxLength": 100 } }, "type": "object", "required": [ "amount", "accountName", "accountNumber", "branchCode" ] }, "WalletListEnvelope": { "properties": { "wallets": { "items": { "properties": { "externalReference": { "type": "string" }, "beneficiaryReference": { "type": "integer" }, "walletId": { "nullable": true, "type": "integer" }, "status": { "enum": [ "PROFILE_CREATED", "ACTIVE" ], "type": "string" }, "onboardingId": { "format": "uuid", "type": "string" }, "displayName": { "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "merchant": { "properties": { "name": { "type": "string" } }, "type": "object" }, "error": { "nullable": true, "type": "string" }, "pagination": { "properties": { "hasMore": { "type": "boolean" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" }, "page": { "type": "integer" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" }, "FeeBreakdown": { "type": "object", "description": "Server-calculated ZAR amounts. For integrator cashout, AmountModel is INCLUSIVE and RequestedAmount equals WalletDebit. WalletDebit = RecipientAmount + TotalFees. ProviderFee already represents the quoted provider total.", "required": [ "Currency", "AmountModel", "RequestedAmount", "ProviderFee", "MiCashFee", "TotalFees", "WalletDebit", "RecipientAmount" ], "properties": { "Currency": { "type": "string", "enum": [ "ZAR" ] }, "AmountModel": { "type": "string", "enum": [ "INCLUSIVE" ] }, "RequestedAmount": { "type": "number", "multipleOf": 0.01 }, "ProviderFee": { "type": "number", "minimum": 0, "multipleOf": 0.01 }, "MiCashFee": { "type": "number", "minimum": 0, "multipleOf": 0.01 }, "TotalFees": { "type": "number", "minimum": 0, "multipleOf": 0.01 }, "WalletDebit": { "type": "number", "multipleOf": 0.01 }, "RecipientAmount": { "type": "number", "multipleOf": 0.01 } } } } } }