{ "openapi": "3.1.0", "info": { "title": "Xash Partners API", "version": "1.0.0", "description": "Sell Xash products (airtime, data, ZESA, bills) and collect mobile money from your customers. Every sale is POST /quotes then POST /transactions. 202 means pending, never failed. Full guide: https://docs.partners.xash.co.zw" }, "servers": [ { "url": "https://partners.xash.co.zw/api/v1", "description": "Sandbox and live. The key (xash_test_ or xash_live_) chooses the environment." } ], "security": [ { "bearer": [] } ], "tags": [ { "name": "Account" }, { "name": "Catalogue" }, { "name": "Sales" }, { "name": "Collections" }, { "name": "Top-ups" }, { "name": "Webhooks" } ], "paths": { "/me": { "get": { "operationId": "getMe", "tags": [ "Account" ], "summary": "Who am I", "description": "Your partner, the environment this key is for, your tier, abilities and how much of each limit is used today.", "responses": { "200": { "description": "OK (a replayed request returns the original record with 200)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Me" } } } ] } } } }, "401": { "description": "KEY_INVALID, KEY_ENVIRONMENT_MISMATCH", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ABILITY_MISSING, IP_NOT_ALLOWED, PARTNER_PAUSED, LIVE_NOT_ENABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/balances": { "get": { "operationId": "getBalances", "tags": [ "Account" ], "summary": "Balance", "description": "Available and reserved balance in USD.\n\nNeeds the `balance:read` ability.", "responses": { "200": { "description": "OK (a replayed request returns the original record with 200)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Balance" } } } ] } } } }, "401": { "description": "KEY_INVALID, KEY_ENVIRONMENT_MISMATCH", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ABILITY_MISSING, IP_NOT_ALLOWED, PARTNER_PAUSED, LIVE_NOT_ENABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/statement": { "get": { "operationId": "getStatement", "tags": [ "Account" ], "summary": "Statement", "description": "Ledger entries (top-ups, sales, collections, releases, reversals) with the running balance. Filter with from and to.\n\nNeeds the `balance:read` ability.", "responses": { "200": { "description": "OK (a replayed request returns the original record with 200)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": [ "object", "array", "null" ] } } } } ] } } } }, "401": { "description": "KEY_INVALID, KEY_ENVIRONMENT_MISMATCH", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ABILITY_MISSING, IP_NOT_ALLOWED, PARTNER_PAUSED, LIVE_NOT_ENABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/products": { "get": { "operationId": "listProducts", "tags": [ "Catalogue" ], "summary": "List products", "description": "Everything you can sell, with your price, limits and the recipient fields each product needs. Filter with category, operator and currency.\n\nNeeds the `catalogue:read` ability.", "responses": { "200": { "description": "OK (a replayed request returns the original record with 200)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } } ] } } } }, "401": { "description": "KEY_INVALID, KEY_ENVIRONMENT_MISMATCH", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ABILITY_MISSING, IP_NOT_ALLOWED, PARTNER_PAUSED, LIVE_NOT_ENABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/products/{code}": { "get": { "operationId": "getProduct", "tags": [ "Catalogue" ], "summary": "One product", "description": "A single product by its code, e.g. econet.airtime.\n\nNeeds the `catalogue:read` ability.", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK (a replayed request returns the original record with 200)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" } } } ] } } } }, "401": { "description": "KEY_INVALID, KEY_ENVIRONMENT_MISMATCH", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ABILITY_MISSING, IP_NOT_ALLOWED, PARTNER_PAUSED, LIVE_NOT_ENABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lookups/mobile": { "post": { "operationId": "lookupMobile", "tags": [ "Catalogue" ], "summary": "Identify a phone number", "description": "Returns the operator for a phone number and the products you can sell to it.\n\nNeeds the `catalogue:read` ability.", "responses": { "200": { "description": "OK (a replayed request returns the original record with 200)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": [ "object", "array", "null" ] } } } ] } } } }, "401": { "description": "KEY_INVALID, KEY_ENVIRONMENT_MISMATCH", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ABILITY_MISSING, IP_NOT_ALLOWED, PARTNER_PAUSED, LIVE_NOT_ENABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_FAILED, RECIPIENT_INVALID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/branches": { "get": { "operationId": "listBranches", "tags": [ "Catalogue" ], "summary": "List branches", "description": "Your branches, for tagging sales and collections.\n\nNeeds the `catalogue:read` ability.", "responses": { "200": { "description": "OK (a replayed request returns the original record with 200)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": [ "object", "array", "null" ] } } } } ] } } } }, "401": { "description": "KEY_INVALID, KEY_ENVIRONMENT_MISMATCH", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ABILITY_MISSING, IP_NOT_ALLOWED, PARTNER_PAUSED, LIVE_NOT_ENABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/quotes": { "post": { "operationId": "createQuote", "tags": [ "Sales" ], "summary": "Quote a sale", "description": "Step 1 of every sale. Validates the recipient (meter name, biller account) and returns the price, fee and total debit. Quotes last 5 minutes.\n\nNeeds the `transactions:write` ability.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" } } } }, "responses": { "200": { "description": "OK (a replayed request returns the original record with 200)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Quote" } } } ] } } } }, "401": { "description": "KEY_INVALID, KEY_ENVIRONMENT_MISMATCH", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "INSUFFICIENT_BALANCE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ABILITY_MISSING, IP_NOT_ALLOWED, PARTNER_PAUSED, LIVE_NOT_ENABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "PRODUCT_UNAVAILABLE, LIMIT_EXCEEDED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_FAILED, RECIPIENT_INVALID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transactions": { "post": { "operationId": "createTransaction", "tags": [ "Sales" ], "summary": "Make a sale", "description": "Step 2: spend a quote. 201 means completed. 202 means pending: wait for the webhook or GET it, and never buy again. Replaying the same reference and Idempotency-Key returns the original sale.\n\nNeeds the `transactions:write` ability.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRequest" } } } }, "responses": { "201": { "description": "Completed", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Transaction" } } } ] } } } }, "202": { "description": "Pending. Not a failure: wait for the webhook or GET the record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Transaction" } } } ] } } } }, "200": { "description": "OK (a replayed request returns the original record with 200)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Transaction" } } } ] } } } }, "401": { "description": "KEY_INVALID, KEY_ENVIRONMENT_MISMATCH", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "INSUFFICIENT_BALANCE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ABILITY_MISSING, IP_NOT_ALLOWED, PARTNER_PAUSED, LIVE_NOT_ENABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "QUOTE_EXPIRED, QUOTE_USED, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS, LIMIT_EXCEEDED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED, VELOCITY_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "UPSTREAM_UNAVAILABLE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listTransactions", "tags": [ "Sales" ], "summary": "List or find sales", "description": "Filter by reference, status, branch_id, from and to.\n\nNeeds the `transactions:read` ability.", "responses": { "200": { "description": "OK (a replayed request returns the original record with 200)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } } } } ] } } } }, "401": { "description": "KEY_INVALID, KEY_ENVIRONMENT_MISMATCH", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ABILITY_MISSING, IP_NOT_ALLOWED, PARTNER_PAUSED, LIVE_NOT_ENABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transactions/{id}": { "get": { "operationId": "getTransaction", "tags": [ "Sales" ], "summary": "One sale", "description": "The authoritative status of a sale, with the token or PIN and receipt data once completed.\n\nNeeds the `transactions:read` ability.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK (a replayed request returns the original record with 200)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Transaction" } } } ] } } } }, "401": { "description": "KEY_INVALID, KEY_ENVIRONMENT_MISMATCH", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ABILITY_MISSING, IP_NOT_ALLOWED, PARTNER_PAUSED, LIVE_NOT_ENABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections": { "post": { "operationId": "createCollection", "tags": [ "Collections" ], "summary": "Collect from a customer", "description": "Starts an EcoCash, OMari or InnBucks payment from your customer into your balance. Always 202 pending first; next_action says what happens next. Collections are free, and the money is spend-only.\n\nNeeds the `collections:write` ability.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionRequest" } } } }, "responses": { "202": { "description": "Pending. Not a failure: wait for the webhook or GET the record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Collection" } } } ] } } } }, "200": { "description": "OK (a replayed request returns the original record with 200)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Collection" } } } ] } } } }, "401": { "description": "KEY_INVALID, KEY_ENVIRONMENT_MISMATCH", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ABILITY_MISSING, IP_NOT_ALLOWED, PARTNER_PAUSED, LIVE_NOT_ENABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "COLLECTION_METHOD_UNAVAILABLE, LIMIT_EXCEEDED, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "UPSTREAM_UNAVAILABLE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listCollections", "tags": [ "Collections" ], "summary": "List or find collections", "description": "Filter by reference, status, method, branch_id, from and to.\n\nNeeds the `collections:read` ability.", "responses": { "200": { "description": "OK (a replayed request returns the original record with 200)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } } } } ] } } } }, "401": { "description": "KEY_INVALID, KEY_ENVIRONMENT_MISMATCH", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ABILITY_MISSING, IP_NOT_ALLOWED, PARTNER_PAUSED, LIVE_NOT_ENABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{id}/confirm": { "post": { "operationId": "confirmCollection", "tags": [ "Collections" ], "summary": "Confirm an OMari collection", "description": "Submit the OTP your customer received.\n\nNeeds the `collections:write` ability.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionConfirmRequest" } } } }, "responses": { "202": { "description": "Pending. Not a failure: wait for the webhook or GET the record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Collection" } } } ] } } } }, "401": { "description": "KEY_INVALID, KEY_ENVIRONMENT_MISMATCH", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ABILITY_MISSING, IP_NOT_ALLOWED, PARTNER_PAUSED, LIVE_NOT_ENABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_FAILED, OTP_INVALID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{id}": { "get": { "operationId": "getCollection", "tags": [ "Collections" ], "summary": "One collection", "description": "The authoritative status of a collection.\n\nNeeds the `collections:read` ability.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK (a replayed request returns the original record with 200)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Collection" } } } ] } } } }, "401": { "description": "KEY_INVALID, KEY_ENVIRONMENT_MISMATCH", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ABILITY_MISSING, IP_NOT_ALLOWED, PARTNER_PAUSED, LIVE_NOT_ENABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/fundings": { "post": { "operationId": "createFunding", "tags": [ "Top-ups" ], "summary": "Top up by mobile money or USDT", "description": "Starts a top-up of your own balance. Bank transfers are matched by Finance using your partner code as the payment reference.\n\nNeeds the `funding:write` ability.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Pending. Not a failure: wait for the webhook or GET the record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": [ "object", "array", "null" ] } } } ] } } } }, "401": { "description": "KEY_INVALID, KEY_ENVIRONMENT_MISMATCH", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ABILITY_MISSING, IP_NOT_ALLOWED, PARTNER_PAUSED, LIVE_NOT_ENABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "LIMIT_EXCEEDED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/fundings/{id}": { "get": { "operationId": "getFunding", "tags": [ "Top-ups" ], "summary": "One top-up", "description": "The status of a top-up.\n\nNeeds the `funding:write` ability.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK (a replayed request returns the original record with 200)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": [ "object", "array", "null" ] } } } ] } } } }, "401": { "description": "KEY_INVALID, KEY_ENVIRONMENT_MISMATCH", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ABILITY_MISSING, IP_NOT_ALLOWED, PARTNER_PAUSED, LIVE_NOT_ENABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/test": { "post": { "operationId": "testWebhook", "tags": [ "Webhooks" ], "summary": "Send a test event", "description": "Sends a signed test event to your webhook URL so you can check your verification code.", "responses": { "202": { "description": "Pending. Not a failure: wait for the webhook or GET the record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": [ "object", "array", "null" ] } } } ] } } } }, "401": { "description": "KEY_INVALID, KEY_ENVIRONMENT_MISMATCH", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ABILITY_MISSING, IP_NOT_ALLOWED, PARTNER_PAUSED, LIVE_NOT_ENABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "xash_test_... (sandbox) or xash_live_... (live)" } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "A UUID you generate per sale or collection. On a timeout, send the same request with the same key." } }, "schemas": { "Amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "examples": [ "5.00" ] }, "Currency": { "type": "string", "enum": [ "USD", "ZWG" ] }, "Phone": { "type": "string", "pattern": "^2637\\d{8}$", "examples": [ "263772000000" ] }, "Reference": { "type": "string", "minLength": 6, "maxLength": 64, "pattern": "^[A-Za-z0-9_.:-]+$", "description": "Your own unique id for this sale or collection, e.g. your order number. Sending it again returns the original record instead of creating a new one." }, "BranchTag": { "type": "object", "properties": { "branch_id": { "type": [ "string", "null" ], "description": "One of your branch codes. Set automatically when the key is limited to a branch." }, "terminal_id": { "type": [ "string", "null" ], "maxLength": 64, "description": "Free text naming the till or device." } } }, "Envelope": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } }, "Error": { "type": "object", "required": [ "success", "message", "error" ], "properties": { "success": { "const": false }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code", "hint", "docs_url" ], "properties": { "code": { "type": "string", "enum": [ "KEY_INVALID", "KEY_ENVIRONMENT_MISMATCH", "ABILITY_MISSING", "IP_NOT_ALLOWED", "LIVE_NOT_ENABLED", "PARTNER_PAUSED", "NOT_FOUND", "METHOD_NOT_ALLOWED", "VALIDATION_FAILED", "RECIPIENT_INVALID", "INSUFFICIENT_BALANCE", "LIMIT_EXCEEDED", "QUOTE_EXPIRED", "QUOTE_USED", "IDEMPOTENCY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "PRODUCT_UNAVAILABLE", "COLLECTION_METHOD_UNAVAILABLE", "OTP_INVALID", "RATE_LIMITED", "VELOCITY_LIMITED", "UPSTREAM_UNAVAILABLE", "INTERNAL_ERROR" ] }, "hint": { "type": "string" }, "docs_url": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "errors": { "type": "object", "description": "Field errors, only for VALIDATION_FAILED.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "Me": { "type": "object", "properties": { "partner_code": { "type": "string", "pattern": "^XP-[ABCDEFGHJKMNPQRSTUVWXYZ23456789]{6}$", "examples": [ "XP-4F7K2Q" ] }, "name": { "type": "string" }, "environment": { "type": "string", "enum": [ "test", "live" ] }, "tier": { "type": "string", "enum": [ "starter", "verified", "enterprise" ] }, "abilities": { "type": "array", "items": { "type": "string", "enum": [ "catalogue:read", "balance:read", "transactions:read", "transactions:write", "collections:read", "collections:write", "funding:write" ] } }, "limits": { "$ref": "#/components/schemas/Limits" } } }, "Limits": { "type": "object", "properties": { "sale_max": { "$ref": "#/components/schemas/Amount" }, "sales_today": { "$ref": "#/components/schemas/Amount" }, "sales_daily_max": { "$ref": "#/components/schemas/Amount" }, "collection_max": { "$ref": "#/components/schemas/Amount" }, "collections_today": { "$ref": "#/components/schemas/Amount" }, "collections_daily_max": { "$ref": "#/components/schemas/Amount" } } }, "Balance": { "type": "object", "properties": { "currency": { "const": "USD" }, "available": { "$ref": "#/components/schemas/Amount" }, "reserved": { "$ref": "#/components/schemas/Amount", "description": "Held for pending sales." } } }, "Product": { "type": "object", "properties": { "code": { "type": "string", "examples": [ "econet.airtime", "zetdc.prepaid", "netone.bundle.whatsapp_1gb" ] }, "name": { "type": "string" }, "category": { "type": "string", "enum": [ "airtime", "data", "electricity", "bill", "voucher" ] }, "operator": { "type": "string" }, "kind": { "type": "string", "enum": [ "fixed", "range" ] }, "price": { "$ref": "#/components/schemas/Amount", "description": "Fixed products: what you pay in USD, after your discount." }, "min": { "$ref": "#/components/schemas/Amount" }, "max": { "$ref": "#/components/schemas/Amount" }, "face_value": { "$ref": "#/components/schemas/Amount" }, "face_currency": { "$ref": "#/components/schemas/Currency" }, "required_fields": { "type": "array", "items": { "type": "string" }, "examples": [ [ "recipient.phone" ], [ "recipient.meter" ] ] }, "available": { "type": "boolean" } } }, "QuoteRequest": { "type": "object", "required": [ "product", "recipient" ], "allOf": [ { "$ref": "#/components/schemas/BranchTag" } ], "properties": { "product": { "type": "string" }, "amount": { "$ref": "#/components/schemas/Amount", "description": "Ranged products: USD to spend. Send this or face_value, not both." }, "face_value": { "$ref": "#/components/schemas/Amount", "description": "Ranged products: value in the product's face currency." }, "recipient": { "type": "object", "description": "The fields named in the product's required_fields, e.g. {\"phone\": \"263772000000\"} or {\"meter\": \"37132611234\"}." }, "customer_phone": { "$ref": "#/components/schemas/Phone" } } }, "Quote": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "qt_01JB4Y3KQ2N8F7" ] }, "product": { "type": "string" }, "customer": { "type": [ "object", "null" ], "description": "Name and details the provider returned for the meter or account." }, "face_value": { "$ref": "#/components/schemas/Amount" }, "face_currency": { "$ref": "#/components/schemas/Currency" }, "fee": { "$ref": "#/components/schemas/Amount" }, "total_debit": { "$ref": "#/components/schemas/Amount", "description": "USD that will leave your balance." }, "rate": { "type": [ "object", "null" ], "description": "Only for non-USD face values: the rate version used." }, "expires_at": { "type": "string", "format": "date-time" } } }, "TransactionRequest": { "type": "object", "required": [ "quote_id", "reference" ], "allOf": [ { "$ref": "#/components/schemas/BranchTag" } ], "properties": { "quote_id": { "type": "string" }, "reference": { "$ref": "#/components/schemas/Reference" } } }, "Transaction": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BranchTag" } ], "properties": { "id": { "type": "string", "examples": [ "tx_01JB4Y5R9M2C6D" ] }, "reference": { "$ref": "#/components/schemas/Reference" }, "status": { "type": "string", "enum": [ "pending", "completed", "failed", "reversed" ] }, "product": { "type": "string" }, "total_debit": { "$ref": "#/components/schemas/Amount" }, "balance_after": { "$ref": "#/components/schemas/Amount" }, "fulfilment": { "type": [ "object", "null" ], "description": "Token, PIN or units once completed. Never cached (Cache-Control: no-store)." }, "receipt": { "type": [ "object", "null" ], "description": "Everything needed to print your customer's receipt." }, "failure_code": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CollectionRequest": { "type": "object", "required": [ "method", "amount", "customer_phone", "reference" ], "allOf": [ { "$ref": "#/components/schemas/BranchTag" } ], "properties": { "method": { "type": "string", "enum": [ "ecocash", "omari", "innbucks" ] }, "amount": { "$ref": "#/components/schemas/Amount", "description": "USD to receive." }, "currency": { "$ref": "#/components/schemas/Currency", "description": "What the customer pays in. ZWG is charged at the published collection rate. Default USD." }, "customer_phone": { "$ref": "#/components/schemas/Phone" }, "reference": { "$ref": "#/components/schemas/Reference" } } }, "CollectionConfirmRequest": { "type": "object", "required": [ "otp" ], "properties": { "otp": { "type": "string", "pattern": "^\\d{4,8}$" } } }, "Collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BranchTag" } ], "properties": { "id": { "type": "string", "examples": [ "col_01JB4Y7T3V8X1Q" ] }, "reference": { "$ref": "#/components/schemas/Reference" }, "method": { "type": "string", "enum": [ "ecocash", "omari", "innbucks" ] }, "status": { "type": "string", "enum": [ "pending", "completed", "failed", "reversed" ] }, "charge_amount": { "$ref": "#/components/schemas/Amount" }, "charge_currency": { "$ref": "#/components/schemas/Currency" }, "credit": { "$ref": "#/components/schemas/Amount", "description": "USD credited to your balance (spend-only). Collections are free." }, "next_action": { "type": [ "object", "null" ], "description": "What the customer or you must do next: approve on phone (EcoCash), submit OTP (OMari), or pay this code (InnBucks)." }, "created_at": { "type": "string", "format": "date-time" } } }, "WebhookPayload": { "type": "object", "required": [ "event_id", "type", "occurred_at" ], "properties": { "event_id": { "type": "string" }, "type": { "type": "string", "enum": [ "transaction.completed", "transaction.failed", "transaction.reversed", "collection.completed", "collection.failed", "collection.reversed", "funding.credited", "funding.failed", "balance.low", "partner.limit_reached", "partner.paused" ] }, "object_id": { "type": "string", "description": "The transaction, collection or funding id. GET it for the full record." }, "reference": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "occurred_at": { "type": "string", "format": "date-time" } } } } } }