{ "openapi": "3.1.0", "info": { "title": "JasperFly API", "version": "1.0.0", "description": "Accept Mobile Money and card payments, send payouts, and manage customers, invoices, payment links, plans, subscriptions and storefronts in Ghana.", "contact": { "name": "JasperFly Support", "url": "https://jasperfly.com/contact" } }, "servers": [ { "url": "https://jasperfly.com/api/public/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Account" }, { "name": "Collections" }, { "name": "Payouts" }, { "name": "Customers" }, { "name": "Invoices" }, { "name": "Payment Links" }, { "name": "Plans" }, { "name": "Subscriptions" }, { "name": "Storefronts" }, { "name": "Checkout" }, { "name": "Verifications" }, { "name": "Metadata" }, { "name": "Mandates" }, { "name": "Transactions" }, { "name": "Refunds" }, { "name": "Coupons" }, { "name": "Splits" }, { "name": "Webhooks" } ], "paths": { "/me": { "get": { "tags": [ "Account" ], "operationId": "getMe", "summary": "Retrieve the merchant profile for this key", "responses": { "200": { "description": "Merchant profile", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/balance": { "get": { "tags": [ "Account" ], "operationId": "getBalance", "summary": "Retrieve available and pending balance", "description": "Merchant funds only: available, settled, lifetime and pending-payout totals in pesewas, plus the current payout fees. Test-mode activity never affects these numbers. Prefer webhooks for state changes and poll this endpoint at most once every few minutes — reads are rate limited to 120 per minute per key.", "responses": { "200": { "description": "Balance in cents", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections": { "get": { "tags": [ "Collections" ], "operationId": "listCollections", "summary": "List collections, optionally by merchant reference", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "reference", "in": "query", "schema": { "type": "string" }, "description": "Your own merchant reference." } ], "responses": { "200": { "description": "A list of collections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Collections" ], "operationId": "createCollection", "summary": "Initiate a collection (Mobile Money, or card via authorization_url)", "description": "payment_rail defaults to momo, which debits the customer's wallet directly. payment_rail: card creates a hosted authorization page and returns authorization_url; open that URL to let the customer pay by card. The response carries both `order_id` (use it for status reads) and `id`, the internal payment id accepted as `source_id` on POST /refunds. On the momo rail `network` is optional (detected from the number prefix) and `description` defaults to Payment; when `customer_name` is omitted the wallet's registered name is resolved automatically and returned as `customer_name` with `customer_name_source`. While the platform's payment provider account is in Testing mode, amounts above the platform testing cap are rejected with invalid_parameter.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Safely retry a write. Replaying the same key with the same body returns the original response with `idempotent_replay: true`.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionCreate" } } } }, "responses": { "200": { "description": "The created collection", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{orderId}": { "get": { "tags": [ "Collections" ], "operationId": "getCollection", "summary": "Retrieve a collection by JasperFly order id", "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The collection", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/payouts": { "post": { "tags": [ "Payouts" ], "operationId": "createPayout", "summary": "Send a single payout to a Mobile Money wallet", "description": "Payout status is one of pending, processing, succeeded, failed or cancelled, and reads (GET /payouts/{id}, GET /transactions) report the same value the create call returned. In test mode payouts are simulated: they settle as succeeded immediately, emit payout.completed to test webhook endpoints, and never touch rails or your balance.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Safely retry a write. Replaying the same key with the same body returns the original response with `idempotent_replay: true`.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutCreate" } } } }, "responses": { "200": { "description": "The created payout", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/payouts/bulk": { "post": { "tags": [ "Payouts" ], "operationId": "createBulkPayout", "summary": "Send up to 100 payouts in one request", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Safely retry a write. Replaying the same key with the same body returns the original response with `idempotent_replay: true`.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "payouts" ], "properties": { "payouts": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PayoutCreate" } } } } } } }, "responses": { "200": { "description": "Per-item results", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/payouts/{id}": { "get": { "tags": [ "Payouts" ], "operationId": "getPayout", "summary": "Retrieve a payout", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The payout", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/checkout/sessions": { "post": { "tags": [ "Checkout" ], "operationId": "createCheckoutSession", "summary": "Create a hosted checkout session", "description": "Returns a hosted payment URL. payment_rail: card sends the customer straight to the card form; omit it (or send momo) and the customer chooses their wallet on the hosted page. success_url and cancel_url must be https.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Safely retry a write. Replaying the same key with the same body returns the original response with `idempotent_replay: true`.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionCreate" } } } }, "responses": { "200": { "description": "The created checkout session", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/verifications/mobile": { "post": { "tags": [ "Verifications" ], "operationId": "verifyMobile", "summary": "Look up the registered name on a Mobile Money wallet", "description": "Run this before a payout so funds never land on the wrong wallet.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mobile" ], "properties": { "mobile": { "type": "string", "example": "0544338841" }, "network": { "type": "string", "enum": [ "MTN", "AIRTELTIGO", "VODAFONE", "TELECEL" ] } } } } } }, "responses": { "200": { "description": "Verification result with account_name", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/verifications/bank-account": { "post": { "tags": [ "Verifications" ], "operationId": "verifyBankAccount", "summary": "Look up the registered name on a bank account", "description": "Send bank_code from GET /metadata/banks. bank_name is accepted and matched to a code where possible.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_number" ], "properties": { "account_number": { "type": "string" }, "bank_code": { "type": "string" }, "bank_name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Verification result with account_name", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/metadata/mobile-providers": { "get": { "tags": [ "Metadata" ], "operationId": "listMobileProviders", "summary": "List Mobile Money provider codes", "responses": { "200": { "description": "A list of mobile providers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/metadata/banks": { "get": { "tags": [ "Metadata" ], "operationId": "listBanks", "summary": "List banks with the codes bank payouts require", "responses": { "200": { "description": "A list of banks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/mandates": { "get": { "tags": [ "Mandates" ], "operationId": "listMandates", "summary": "List recurring debit mandates", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of mandates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Mandates" ], "operationId": "createMandate", "summary": "Create a recurring debit mandate", "description": "The customer approves the mandate once on their phone. Approval arrives as a mandate.approved webhook, after which debits need no customer action.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Safely retry a write. Replaying the same key with the same body returns the original response with `idempotent_replay: true`.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MandateCreate" } } } }, "responses": { "200": { "description": "The created mandate", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/mandates/{id}": { "get": { "tags": [ "Mandates" ], "operationId": "getMandate", "summary": "Retrieve a mandate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The mandate", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Mandates" ], "operationId": "cancelMandate", "summary": "Cancel a mandate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The cancelled mandate", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/mandates/{id}/debits": { "post": { "tags": [ "Mandates" ], "operationId": "debitMandate", "summary": "Debit an approved mandate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Safely retry a write. Replaying the same key with the same body returns the original response with `idempotent_replay: true`.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount_cents", "reference" ], "properties": { "amount_cents": { "type": "integer", "minimum": 10, "description": "Minimum 10 (GHS 0.10). Must not exceed the mandate's authorised amount." }, "currency": { "type": "string", "enum": [ "GHS" ], "default": "GHS" }, "reference": { "type": "string", "maxLength": 120 }, "description": { "type": "string", "maxLength": 200 } } } } } }, "responses": { "200": { "description": "The mandate debit", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/customers": { "get": { "tags": [ "Customers" ], "operationId": "listCustomers", "summary": "List customers", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of customers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Customers" ], "operationId": "createCustomer", "summary": "Create or upsert a customer", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Safely retry a write. Replaying the same key with the same body returns the original response with `idempotent_replay: true`.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 120 }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "The customer", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/customers/{id}": { "get": { "tags": [ "Customers" ], "operationId": "getCustomer", "summary": "Retrieve a customer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The customer", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/invoices": { "get": { "tags": [ "Invoices" ], "operationId": "listInvoices", "summary": "List invoices", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "A list of invoices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Invoices" ], "operationId": "createInvoice", "summary": "Create a draft or send an invoice", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Safely retry a write. Replaying the same key with the same body returns the original response with `idempotent_replay: true`.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "The invoice", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/invoices/{id}": { "get": { "tags": [ "Invoices" ], "operationId": "getInvoice", "summary": "Retrieve an invoice by id or public slug", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The invoice with line items", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/invoices/{id}/send": { "post": { "tags": [ "Invoices" ], "operationId": "sendInvoice", "summary": "Mark a draft invoice as sent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Safely retry a write. Replaying the same key with the same body returns the original response with `idempotent_replay: true`.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "The updated invoice", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/payment-links": { "get": { "tags": [ "Payment Links" ], "operationId": "listPaymentLinks", "summary": "List payment links", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "A list of payment links", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Payment Links" ], "operationId": "createPaymentLink", "summary": "Create a payment link", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Safely retry a write. Replaying the same key with the same body returns the original response with `idempotent_replay: true`.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "The payment link", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/payment-links/{id}": { "get": { "tags": [ "Payment Links" ], "operationId": "getPaymentLink", "summary": "Retrieve a payment link by id or slug", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The payment link", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/plans": { "get": { "tags": [ "Plans" ], "operationId": "listPlans", "summary": "List billing plans", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "A list of plans", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Plans" ], "operationId": "createPlan", "summary": "Create a recurring billing plan", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Safely retry a write. Replaying the same key with the same body returns the original response with `idempotent_replay: true`.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "The plan", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/plans/{id}": { "get": { "tags": [ "Plans" ], "operationId": "getPlan", "summary": "Retrieve a plan", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The plan", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/subscriptions": { "get": { "tags": [ "Subscriptions" ], "operationId": "listSubscriptions", "summary": "List subscriptions", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "A list of subscriptions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Subscriptions" ], "operationId": "createSubscription", "summary": "Subscribe a customer to a plan", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Safely retry a write. Replaying the same key with the same body returns the original response with `idempotent_replay: true`.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "The subscription", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/subscriptions/{id}": { "get": { "tags": [ "Subscriptions" ], "operationId": "getSubscription", "summary": "Retrieve a subscription", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The subscription", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/subscriptions/{id}/cancel": { "post": { "tags": [ "Subscriptions" ], "operationId": "cancelSubscription", "summary": "Cancel a subscription", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Safely retry a write. Replaying the same key with the same body returns the original response with `idempotent_replay: true`.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "The cancelled subscription", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/storefronts": { "get": { "tags": [ "Storefronts" ], "operationId": "listStorefronts", "summary": "List storefronts", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "A list of storefronts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/storefronts/{id}": { "get": { "tags": [ "Storefronts" ], "operationId": "getStorefront", "summary": "Retrieve a storefront by id or slug", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The storefront", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/storefronts/{id}/products": { "get": { "tags": [ "Storefronts" ], "operationId": "listStorefrontProducts", "summary": "List products in a storefront", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "A list of products", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/checkout-links": { "post": { "tags": [ "Checkout" ], "operationId": "createCheckoutLink", "summary": "Generate a hosted checkout URL for a resource", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Safely retry a write. Replaying the same key with the same body returns the original response with `idempotent_replay: true`.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "The hosted checkout URL", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transactions/verify/{reference}": { "get": { "tags": [ "Transactions" ], "operationId": "verifyTransaction", "summary": "Resolve a transaction from your own reference", "description": "One lookup that resolves a collection, payout or checkout session. Non-terminal transactions are refreshed from the payment provider before the response is returned.", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The transaction, with a provider_snapshot when it was refreshed", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transactions": { "get": { "tags": [ "Transactions" ], "operationId": "listTransactions", "summary": "Unified search across collections and payouts", "description": "Reconciliation endpoint. Returns collections and payouts in one list, each carrying both JasperFly's `order_id` and your own `reference`, plus any `metadata` you attached at creation.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "collection", "payout" ] } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "order_id", "in": "query", "description": "Exact match on the JasperFly order id.", "schema": { "type": "string" } }, { "name": "reference", "in": "query", "description": "Exact match on your own merchant reference.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Fuzzy match across order id, reference and customer.", "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "amount_min_cents", "in": "query", "schema": { "type": "integer" } }, { "name": "amount_max_cents", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "A list of transactions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/refunds": { "get": { "tags": [ "Refunds" ], "operationId": "listRefunds", "summary": "List refunds", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "succeeded", "failed" ] } }, { "name": "source_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A list of refunds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Refunds" ], "operationId": "createRefund", "summary": "Refund a payment back to the customer's Mobile Money wallet", "description": "Funded from your JasperFly balance. Identify the payment being refunded with either source_id (plus source_type), the order_id returned when the payment was created, or your own reference — order_id and reference resolve source_type for you. Returns 422 insufficient_balance when the balance does not cover the refund, and 422 amount_too_large when it exceeds the refundable remainder. In test mode the refund settles immediately without contacting the provider.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Safely retry a write. Replaying the same key with the same body returns the original response with `idempotent_replay: true`.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount_cents" ], "properties": { "source_type": { "type": "string", "enum": [ "instant_charge", "payment_link", "invoice", "order", "subscription_invoice" ], "description": "Required only when identifying the payment by source_id." }, "source_id": { "type": "string", "format": "uuid", "description": "Internal id of the payment, returned as `id` on collection create and read." }, "order_id": { "type": "string", "description": "JasperFly order id of the payment, e.g. API1786…. Resolves source_type automatically." }, "reference": { "type": "string", "description": "Your own reference on the payment. Resolves source_type automatically." }, "amount_cents": { "type": "integer", "description": "Refund amount in pesewas." }, "amount": { "type": "number", "description": "Refund amount in cedis. Alias for amount_cents." }, "reason": { "type": "string", "maxLength": 500 }, "recipient_phone": { "type": "string", "description": "Overrides the number on file." }, "mobile_network": { "type": "string", "enum": [ "MTN", "AIRTELTIGO", "VODAFONE" ], "default": "MTN" } } }, "examples": { "by_order_id": { "summary": "Refund by order_id (simplest — use the order_id from the collection response)", "value": { "order_id": "API1786102281613ULEEA7", "amount_cents": 500, "reason": "Customer cancelled" } }, "by_source_id": { "summary": "Refund by internal payment id (source_id needs source_type)", "value": { "source_id": "3c659c84-0a5f-438c-98f8-5ef32ac56ede", "source_type": "instant_charge", "amount_cents": 500 } } } } } }, "responses": { "200": { "description": "The refund", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/refunds/{id}": { "get": { "tags": [ "Refunds" ], "operationId": "getRefund", "summary": "Retrieve a refund by id or order id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The refund", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/coupons": { "get": { "tags": [ "Coupons" ], "operationId": "listCoupons", "summary": "List coupons", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "paused", "expired" ] } }, { "name": "code", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of coupons", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Coupons" ], "operationId": "createCoupon", "summary": "Create a discount coupon", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Safely retry a write. Replaying the same key with the same body returns the original response with `idempotent_replay: true`.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "type", "value" ], "properties": { "code": { "type": "string", "description": "Case-insensitive. Letters, numbers, hyphen and underscore." }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "percent", "fixed" ] }, "value": { "type": "number", "description": "1-100 for percent coupons; pesewas for fixed coupons." }, "min_subtotal_cents": { "type": "integer" }, "min_subtotal": { "type": "number", "description": "Cedi alias for min_subtotal_cents." }, "applies_to": { "type": "array", "items": { "type": "string", "enum": [ "storefront", "payment_link", "invoice", "subscription" ] } }, "max_redemptions": { "type": "integer" }, "valid_from": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "paused" ], "default": "active" } } } } } }, "responses": { "200": { "description": "The coupon", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/coupons/{id}": { "get": { "tags": [ "Coupons" ], "operationId": "getCoupon", "summary": "Retrieve a coupon by id or code", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The coupon", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Coupons" ], "operationId": "updateCoupon", "summary": "Update a coupon", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "max_redemptions": { "type": "integer" }, "min_subtotal_cents": { "type": "integer" }, "valid_until": { "type": "string", "format": "date-time" } } } } } }, "responses": { "200": { "description": "The updated coupon", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Coupons" ], "operationId": "deactivateCoupon", "summary": "Deactivate a coupon (redemption history is preserved)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The deactivated coupon", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/splits": { "get": { "tags": [ "Splits" ], "operationId": "listSplitGroups", "summary": "List split groups with their recipients", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "A list of split groups", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Splits" ], "operationId": "createSplitGroup", "summary": "Create a split group", "description": "Attach the returned id to a collection as `split_group_id` to share its proceeds.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Safely retry a write. Replaying the same key with the same body returns the original response with `idempotent_replay: true`.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "recipients" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "recipients": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "required": [ "label", "type", "bank_or_provider", "account_number", "share_type", "share_value" ], "properties": { "label": { "type": "string" }, "type": { "type": "string", "enum": [ "bank", "momo" ] }, "bank_or_provider": { "type": "string" }, "account_number": { "type": "string" }, "account_name": { "type": "string" }, "share_type": { "type": "string", "enum": [ "percent", "fixed" ] }, "share_value": { "type": "number", "description": "0-100 for percent shares; pesewas for fixed shares." } } } } } } } } }, "responses": { "200": { "description": "The split group", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/splits/{id}": { "get": { "tags": [ "Splits" ], "operationId": "getSplitGroup", "summary": "Retrieve a split group", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The split group", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Splits" ], "operationId": "deleteSplitGroup", "summary": "Delete a split group", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deletion confirmation", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook-endpoints": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookEndpoints", "summary": "List webhook endpoints", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "A list of webhook endpoints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Webhooks" ], "operationId": "createWebhookEndpoint", "summary": "Register a webhook endpoint", "description": "The signing secret is returned once, in this response only. Store it to verify the X-JasperFly-Signature header. The endpoint belongs to the environment of the key that registers it: a jf_test_ key creates a test endpoint that only receives sandbox events, and a jf_live_ key creates a live endpoint that only receives live events. List, update and delete are likewise scoped to the calling key's environment.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Safely retry a write. Replaying the same key with the same body returns the original response with `idempotent_replay: true`.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Must be https." }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "is_active": { "type": "boolean", "default": true } } } } } }, "responses": { "200": { "description": "The webhook endpoint, including its secret and its env (test or live)", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook-endpoints/{id}": { "get": { "tags": [ "Webhooks" ], "operationId": "getWebhookEndpoint", "summary": "Retrieve a webhook endpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The webhook endpoint", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Webhooks" ], "operationId": "updateWebhookEndpoint", "summary": "Update an endpoint or rotate its secret", "description": "Set rotate_secret to true to issue a new secret. The previous secret keeps verifying for 24 hours.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "rotate_secret": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "The updated endpoint", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhookEndpoint", "summary": "Delete a webhook endpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deletion confirmation", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, caller IP not on the key allowlist (ip_not_allowed), or a secret key was used from a browser", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate reference or idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Secret API key. `jf_test_...` runs in test mode (no money moves); `jf_live_...` moves real money. Server-side only: requests carrying an `Origin` header are rejected. Keys may also carry an optional IP allowlist; calls from other addresses return 403 ip_not_allowed." } }, "schemas": { "Error": { "type": "object", "required": [ "error", "request_id" ], "properties": { "error": { "type": "object", "required": [ "type", "code", "message" ], "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "rate_limit_error", "idempotency_error", "api_error" ] }, "code": { "type": "string", "examples": [ "invalid_api_key", "duplicate_reference", "rate_limited" ] }, "message": { "type": "string" }, "param": { "type": "string" }, "doc_url": { "type": "string", "format": "uri" } } }, "request_id": { "type": "string", "examples": [ "req_9f2c..." ] } } }, "List": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true }, "limit": { "type": "integer" } } }, "CollectionCreate": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number", "description": "Amount in GHS (major units, max 2 decimals). Send this or amount_cents, not both unless they agree. Minimum GHS 0.10 (10 pesewas)." }, "amount_cents": { "type": "integer", "description": "Amount in pesewas (minor units). Alternative to amount; responses always return both." }, "customer_phone": { "type": "string", "examples": [ "+233200000000" ], "description": "Required for the momo rail. Ignored on the card rail." }, "customer_name": { "type": "string", "description": "Optional. On the momo rail, when omitted we look up the wallet's registered name and return it as customer_name with customer_name_source: wallet_lookup." }, "network": { "type": "string", "enum": [ "MTN", "AIRTELTIGO", "TELECEL", "VODAFONE" ], "description": "Optional on the momo rail: when omitted we detect it from the Ghana number prefix, and only reject the request when the prefix is unrecognised. TELECEL and VODAFONE are the same network." }, "payment_rail": { "type": "string", "enum": [ "momo", "card" ], "default": "momo", "description": "momo debits a Mobile Money wallet directly. card returns an authorization_url that the customer must open to enter card details; customer_email is then required, and phone/network are not used." }, "customer_email": { "type": "string", "format": "email", "description": "Required when payment_rail is card." }, "description": { "type": "string", "default": "Payment", "description": "Optional. Defaults to \"Payment\" when omitted." }, "reference": { "type": "string", "description": "Your own reference. Unique per environment; duplicates return 409." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Up to 20 string key/value pairs echoed on responses, webhooks and CSV exports." }, "split_group_id": { "type": "string", "format": "uuid", "description": "Optional split group. Its recipients receive their shares once the payment settles." } } }, "PayoutCreate": { "type": "object", "required": [ "kind", "amount", "recipient_name" ], "properties": { "kind": { "type": "string", "enum": [ "momo", "bank" ], "description": "momo pays a Mobile Money wallet; bank pays a bank account." }, "amount": { "type": "number", "description": "Amount in GHS (major units, max 2 decimals). Send this or amount_cents. Minimum GHS 1.00 for payouts." }, "amount_cents": { "type": "integer", "description": "Amount in pesewas (minor units). Alternative to amount; responses always return both." }, "recipient_name": { "type": "string" }, "recipient_phone": { "type": "string", "description": "Required when kind is momo." }, "recipient_email": { "type": "string", "format": "email" }, "mobile_network": { "type": "string", "enum": [ "MTN", "AIRTELTIGO", "TELECEL", "VODAFONE" ], "description": "Required when kind is momo. TELECEL is accepted as an alias for VODAFONE." }, "bank_code": { "type": "string", "description": "Required when kind is bank. Use a code from GET /metadata/banks." }, "bank_name": { "type": "string", "description": "Accepted instead of bank_code and matched to a code where possible." }, "branch_sort_code": { "type": "string", "description": "Optional." }, "account_number": { "type": "string", "description": "Required when kind is bank." }, "account_title": { "type": "string" }, "reference": { "type": "string", "description": "Your own reference for this payout." }, "narration": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Up to 20 string key/value pairs echoed on responses, webhooks and CSV exports." } } }, "CheckoutSessionCreate": { "type": "object", "required": [ "amount", "reference", "success_url" ], "properties": { "amount": { "type": "number", "description": "Amount in GHS (major units, max 2 decimals). Send this or amount_cents. Minimum GHS 0.10 (10 pesewas)." }, "amount_cents": { "type": "integer", "description": "Amount in pesewas (minor units). Alternative to amount." }, "currency": { "type": "string", "enum": [ "GHS" ], "default": "GHS" }, "payment_rail": { "type": "string", "enum": [ "card", "momo" ], "nullable": true, "description": "card sends the customer straight to the card form. momo or null lets the customer pick their wallet on the hosted page." }, "customer_phone": { "type": "string" }, "network": { "type": "string", "enum": [ "MTN", "AIRTELTIGO", "TELECEL", "VODAFONE" ] }, "description": { "type": "string", "maxLength": 200 }, "reference": { "type": "string", "maxLength": 120, "description": "Your own reference. Reconcile with GET /transactions/verify/{reference}." }, "success_url": { "type": "string", "format": "uri", "description": "Must be https." }, "cancel_url": { "type": "string", "format": "uri", "description": "Must be https. Defaults to success_url." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } } }, "MandateCreate": { "type": "object", "required": [ "amount", "customer_phone", "network", "frequency", "starts_at", "ends_at", "reference" ], "properties": { "amount": { "type": "number", "description": "Maximum amount authorised per cycle, in GHS. Send this or amount_cents. Minimum GHS 0.10 (10 pesewas)." }, "amount_cents": { "type": "integer", "description": "Maximum amount authorised per cycle, in pesewas." }, "currency": { "type": "string", "enum": [ "GHS" ], "default": "GHS" }, "customer_phone": { "type": "string" }, "network": { "type": "string", "enum": [ "MTN", "AIRTELTIGO", "TELECEL", "VODAFONE" ] }, "frequency": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY" ] }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time", "description": "Must be after starts_at." }, "reference": { "type": "string", "maxLength": 120 }, "description": { "type": "string", "maxLength": 200 }, "plan_id": { "type": "string", "description": "Links the mandate to a billing plan. customer_name and customer_email are then required." }, "customer_name": { "type": "string" }, "customer_email": { "type": "string", "format": "email" } } } } }, "x-rate-limits": { "default": "120 requests per minute per API key per endpoint", "POST /collections": "60 per minute", "POST /checkout/sessions": "60 per minute", "POST /verifications/mobile": "60 per minute", "POST /verifications/bank-account": "60 per minute", "POST /mandates": "30 per minute", "POST /mandates/{id}/debits": "60 per minute", "POST /payouts": "30 per minute", "POST /payouts/bulk": "10 per minute", "headers": [ "X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset", "Retry-After" ] }, "x-scopes": { "description": "API keys can be limited to a set of scopes. `*` grants full access.", "values": [ "account:read", "balance:read", "collections:read", "collections:write", "payouts:read", "payouts:write", "customers:read", "customers:write", "invoices:read", "invoices:write", "payment_links:read", "payment_links:write", "plans:read", "plans:write", "subscriptions:read", "subscriptions:write", "storefronts:read", "checkout:write", "refunds:read", "refunds:write", "coupons:read", "coupons:write", "splits:read", "splits:write", "transactions:read", "verifications:write", "metadata:read", "mandates:read", "mandates:write", "webhooks:read", "webhooks:write" ] } }