{ "openapi": "3.0.3", "info": { "title": "Wajub API", "description": "Africa's payment orchestrator REST API.", "version": "2026-08-01", "contact": { "name": "Wajub", "url": "https://wajub.com", "email": "hello@wajub.com" }, "termsOfService": "https://wajub.com/terms" }, "servers": [ { "url": "https://api.wajub.com", "description": "API — test mode is controlled by your API key (pk_test.… / sk_test.…), not the URL." } ], "tags": [ { "name": "Payments", "description": "" }, { "name": "Refunds", "description": "" }, { "name": "Transfers", "description": "" }, { "name": "Customers", "description": "\nCreate and manage reusable customer profiles. Linking a customer to a payment\nenables transaction history, better success-rate optimization, and reduces\nfriction for returning payers." }, { "name": "Beneficiaries", "description": "\nPre-registered transfer recipients. Save frequently-used recipients as\nbeneficiaries to simplify your payout API calls." }, { "name": "Balance", "description": "" }, { "name": "Events", "description": "\nRead and replay merchant events (powers `wajub events list/retrieve/resend`).\nEvents are the source of truth for webhook deliveries; resending re-runs the\ndelivery pipeline to all matching active endpoints." }, { "name": "Webhook Endpoints", "description": "\nManage webhook endpoint subscriptions. When a subscribed event fires, Wajub\nsends a signed HTTP POST to your endpoint URL." }, { "name": "General", "description": "" }, { "name": "Invoices", "description": "\nCreate, send, and track one-off or recurring invoices. Live environment only." }, { "name": "Payment Links", "description": "\nNo-code payment links — shareable URLs that let customers pay without writing any integration code.\nLive environment only." }, { "name": "Subaccounts", "description": "\nMerchant subaccounts for marketplace and platform use cases (Sync product).\nEach subaccount can receive a percentage or fixed amount split from payments." } ], "components": { "securitySchemes": { "default": { "type": "apiKey", "name": "Authorization", "in": "header", "description": "Use a **public key** (`pk.`/`pk_test.`) for payment initialization. Use a **secret key** (`sk.`/`sk_test.`) for sensitive operations (transfers, refunds, balance), or a **restricted key** (`rk.`/`rk_test.`) scoped to specific permissions. The `_test.` variant of any key selects the sandbox environment — there is no separate sandbox URL. Never expose your secret key in client-side code." } } }, "security": [ { "default": [] } ], "paths": { "/payments": { "get": { "summary": "List payments.", "operationId": "listPayments", "description": "Returns a paginated list of transactions for the authenticated account and environment.\nSupports both offset pagination (`per_page` + `page`) and cursor pagination (`cursor`)\nfor large datasets.", "parameters": [], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "status": "OK", "message": "Payments retrieved", "items": [ { "id": "trx_01JXXXXXXXXXXXXX", "reference": "trx.PVrU8x2kQ1", "amount": 25000, "currency": "XAF", "status": "succeeded", "channel": "cm.mtn", "description": "Order #4172", "sandbox": false, "created_at": "2026-01-15T10:30:00Z" } ], "meta": { "current_page": 1, "last_page": 3, "per_page": 25, "total": 68 } }, "properties": { "code": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "OK" }, "message": { "type": "string", "example": "Payments retrieved" }, "items": { "type": "array", "example": [ { "id": "trx_01JXXXXXXXXXXXXX", "reference": "trx.PVrU8x2kQ1", "amount": 25000, "currency": "XAF", "status": "succeeded", "channel": "cm.mtn", "description": "Order #4172", "sandbox": false, "created_at": "2026-01-15T10:30:00Z" } ], "items": { "type": "object", "properties": { "id": { "type": "string", "example": "trx_01JXXXXXXXXXXXXX" }, "reference": { "type": "string", "example": "trx.PVrU8x2kQ1" }, "amount": { "type": "integer", "example": 25000 }, "currency": { "type": "string", "example": "XAF" }, "status": { "type": "string", "example": "succeeded" }, "channel": { "type": "string", "example": "cm.mtn" }, "description": { "type": "string", "example": "Order #4172" }, "sandbox": { "type": "boolean", "example": false }, "created_at": { "type": "string", "example": "2026-01-15T10:30:00Z" } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 3 }, "per_page": { "type": "integer", "example": 25 }, "total": { "type": "integer", "example": 68 } } } } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 401, "status": "Unauthorized", "message": "Invalid API credentials" }, "properties": { "code": { "type": "integer", "example": 401 }, "status": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid API credentials" } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 429, "status": "Too Many Requests" }, "properties": { "code": { "type": "integer", "example": 429 }, "status": { "type": "string", "example": "Too Many Requests" } } } } } } }, "tags": [ "Payments" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "per_page": { "type": "integer", "description": "Must be at least 1. Must not be greater than 100.", "example": 1, "nullable": true }, "cursor": { "type": "string", "description": "", "example": "architecto", "nullable": true }, "search": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "n", "nullable": true }, "status": { "type": "string", "description": "", "example": "succeeded", "enum": [ "pending", "processing", "succeeded", "expired", "partial", "failed", "cancelled", "refunded", "partially_refunded" ], "nullable": true }, "date_from": { "type": "string", "description": "Must be a valid date.", "example": "2026-07-25T10:10:46", "nullable": true }, "date_to": { "type": "string", "description": "Must be a valid date. Must be a date after or equal to date_from.", "example": "2052-08-17", "nullable": true }, "amount_min": { "type": "number", "description": "Must be at least 0.", "example": 39, "nullable": true }, "amount_max": { "type": "number", "description": "Must be at least 0.", "example": 84, "nullable": true } } } } } } }, "post": { "summary": "Create payment.", "operationId": "createPayment", "description": "Creates a pending transaction and returns a hosted payment URL (`authorization_url`).\nRedirect the customer to this URL to complete the payment on Wajub's hosted page.\nAlways verify the final status server-side via `GET /payments/{id}` or by\nlistening to the `payment.succeeded` webhook — never rely solely on the redirect URL.\nMarketplaces can attribute this payment to a connected subaccount via the `X-Sync` header.", "parameters": [], "responses": { "201": { "description": "Payment initialized", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 201, "status": "Created", "message": "Payment initiated", "authorization_url": "https://pay.wajub.com/tok_xxxxx", "authorization_token": "1|tok_xxxxx", "transaction": { "id": "trx_01JXXXXXXXXXXXXX", "reference": "order-4172", "amount": 25000, "currency": "XAF", "status": "pending", "description": "Order #4172", "sandbox": true, "created_at": "2026-01-15T10:30:00Z" } }, "properties": { "code": { "type": "integer", "example": 201 }, "status": { "type": "string", "example": "Created" }, "message": { "type": "string", "example": "Payment initiated" }, "authorization_url": { "type": "string", "example": "https://pay.wajub.com/tok_xxxxx" }, "authorization_token": { "type": "string", "example": "1|tok_xxxxx" }, "transaction": { "type": "object", "properties": { "id": { "type": "string", "example": "trx_01JXXXXXXXXXXXXX" }, "reference": { "type": "string", "example": "order-4172" }, "amount": { "type": "number", "example": 25000 }, "currency": { "type": "string", "example": "XAF" }, "status": { "type": "string", "example": "pending" }, "description": { "type": "string", "example": "Order #4172" }, "sandbox": { "type": "boolean", "example": true }, "created_at": { "type": "string", "example": "2026-01-15T10:30:00Z" } } } } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 401, "status": "Unauthorized", "message": "Invalid API credentials" }, "properties": { "code": { "type": "integer", "example": 401 }, "status": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid API credentials" } } } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 422, "status": "Unprocessable Content", "message": "The given data was invalid.", "errors": { "amount": [ "The amount field is required." ], "currency": [ "The selected currency is invalid." ] } }, "properties": { "code": { "type": "integer", "example": 422 }, "status": { "type": "string", "example": "Unprocessable Content" }, "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "properties": { "amount": { "type": "array", "example": [ "The amount field is required." ], "items": { "type": "string" } }, "currency": { "type": "array", "example": [ "The selected currency is invalid." ], "items": { "type": "string" } } } } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 429, "status": "Too Many Requests", "message": "Too Many requests. Merchant limit : 120" }, "properties": { "code": { "type": "integer", "example": 429 }, "status": { "type": "string", "example": "Too Many Requests" }, "message": { "type": "string", "example": "Too Many requests. Merchant limit : 120" } } } } } } }, "tags": [ "Payments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Must be at least 0.01.", "example": 27 }, "currency": { "type": "string", "description": "Must match an existing stored value. Must be 3 characters.", "example": "ngz" }, "email": { "type": "string", "description": "This field is required when none of customer_id, phone, and customer are present. Must be a valid email address. Must not be greater than 255 characters.", "example": "rempel.chadrick@example.org", "nullable": true }, "customer_id": { "type": "string", "description": "This field is required when none of email, phone, and customer are present. Must not be greater than 64 characters.", "example": "l", "nullable": true }, "phone": { "type": "string", "description": "This field is required when none of customer_id, email, and customer are present. Must not be greater than 32 characters.", "example": "j", "nullable": true }, "name": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "n", "nullable": true }, "description": { "type": "string", "description": "Must not be greater than 500 characters.", "example": "Modi deserunt aut ab provident perspiciatis.", "nullable": true }, "reference": { "type": "string", "description": "Must not be greater than 128 characters.", "example": "c", "nullable": true }, "callback": { "type": "string", "description": "Must be a valid URL. Must not be greater than 2048 characters.", "example": "m", "nullable": true }, "expires": { "type": "object", "description": "", "example": [], "properties": { "in": { "type": "integer", "description": "Must be at least 5. Must not be greater than 43200.", "example": 8, "nullable": true } } }, "customer": { "type": "string", "description": "", "example": null, "nullable": true }, "theming": { "type": "object", "description": "", "example": null, "properties": {}, "nullable": true }, "address": { "type": "object", "description": "", "example": null, "properties": {}, "nullable": true }, "shipping": { "type": "object", "description": "", "example": null, "properties": {}, "nullable": true }, "items": { "type": "array", "description": "", "example": null, "items": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "u", "nullable": true }, "description": { "type": "string", "description": "Must not be greater than 1000 characters.", "example": "Quidem nostrum qui commodi incidunt iure odit.", "nullable": true }, "quantity": { "type": "number", "description": "Must be at least 0.", "example": 57, "nullable": true } } } }, "telemetry": { "type": "object", "description": "", "example": null, "properties": {}, "nullable": true }, "metadata": { "type": "object", "description": "", "example": null, "properties": {}, "nullable": true }, "bearer": { "type": "string", "description": "", "example": "customer", "enum": [ "merchant", "customer" ], "nullable": true } }, "required": [ "amount", "currency" ] } } } } } }, "/payments/{id}": { "get": { "summary": "Retrieve a payment.", "operationId": "retrieveAPayment", "description": "Returns a single payment transaction by its unique identifier (`reference`).\nAlways call this endpoint server-side to verify the final status before fulfilling an order.", "parameters": [], "responses": { "200": { "description": "Payment retrieved", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "status": "OK", "message": "Payment retrieved", "transaction": { "id": "trx_01JXXXXXXXXXXXXX", "reference": "order-4172", "amount": 25000, "currency": "XAF", "status": "succeeded", "channel": "cm.mtn", "description": "Order #4172", "settled": true, "sandbox": false, "customer": { "id": "cus_01JXXX", "email": "amina@example.com" }, "created_at": "2026-01-15T10:30:00Z" } }, "properties": { "code": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "OK" }, "message": { "type": "string", "example": "Payment retrieved" }, "transaction": { "type": "object", "properties": { "id": { "type": "string", "example": "trx_01JXXXXXXXXXXXXX" }, "reference": { "type": "string", "example": "order-4172" }, "amount": { "type": "number", "example": 25000 }, "currency": { "type": "string", "example": "XAF" }, "status": { "type": "string", "example": "succeeded" }, "channel": { "type": "string", "example": "cm.mtn" }, "description": { "type": "string", "example": "Order #4172" }, "settled": { "type": "boolean", "example": true }, "sandbox": { "type": "boolean", "example": false }, "customer": { "type": "object", "properties": { "id": { "type": "string", "example": "cus_01JXXX" }, "email": { "type": "string", "example": "amina@example.com" } } }, "created_at": { "type": "string", "example": "2026-01-15T10:30:00Z" } } } } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 401, "status": "Unauthorized", "message": "Invalid API credentials" }, "properties": { "code": { "type": "integer", "example": 401 }, "status": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid API credentials" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 404, "status": "Not Found", "message": "Payment Not Found" }, "properties": { "code": { "type": "integer", "example": 404 }, "status": { "type": "string", "example": "Not Found" }, "message": { "type": "string", "example": "Payment Not Found" } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 429, "status": "Too Many Requests" }, "properties": { "code": { "type": "integer", "example": 429 }, "status": { "type": "string", "example": "Too Many Requests" } } } } } } }, "tags": [ "Payments" ] }, "delete": { "summary": "Cancel payment.", "operationId": "cancelPayment", "description": "Cancels a `pending` or `processing` payment. Once cancelled, the transaction cannot be restarted.\nOnly payments that have not yet been completed can be cancelled.", "parameters": [], "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "status": "OK", "message": "Payment cancelled", "transaction": { "id": "trx_01JXXXXXXXXXXXXX", "status": "cancelled" } }, "properties": { "code": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "OK" }, "message": { "type": "string", "example": "Payment cancelled" }, "transaction": { "type": "object", "properties": { "id": { "type": "string", "example": "trx_01JXXXXXXXXXXXXX" }, "status": { "type": "string", "example": "cancelled" } } } } } } } }, "400": { "description": "Cannot cancel", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 400, "status": "Bad Request", "message": "This payment cannot be cancelled (already completed or expired)." }, "properties": { "code": { "type": "integer", "example": 400 }, "status": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "example": "This payment cannot be cancelled (already completed or expired)." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 404, "status": "Not Found", "message": "Payment Not Found" }, "properties": { "code": { "type": "integer", "example": 404 }, "status": { "type": "string", "example": "Not Found" }, "message": { "type": "string", "example": "Payment Not Found" } } } } } } }, "tags": [ "Payments" ] }, "parameters": [ { "in": "path", "name": "id", "description": "", "example": "architecto", "required": true, "schema": { "type": "string" } } ] }, "/payments/{id}/refunds": { "get": { "summary": "List refunds for a payment.", "operationId": "listRefundsForAPayment", "description": "", "parameters": [], "responses": { "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 401, "status": "Unauthorized", "message": "Invalid API credentials" }, "properties": { "code": { "type": "integer", "example": 401 }, "status": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid API credentials" } } } } } } }, "tags": [ "Payments" ] }, "parameters": [ { "in": "path", "name": "id", "description": "", "example": "architecto", "required": true, "schema": { "type": "string" } } ] }, "/refunds": { "get": { "summary": "List refunds.", "operationId": "listRefunds", "description": "", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "status": "OK", "items": [], "meta": { "total": 0 } }, "properties": { "code": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "OK" }, "items": { "type": "array", "example": [] }, "meta": { "type": "object", "properties": { "total": { "type": "integer", "example": 0 } } } } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 401 }, "properties": { "code": { "type": "integer", "example": 401 } } } } } } }, "tags": [ "Refunds" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "per_page": { "type": "integer", "description": "Must be at least 1. Must not be greater than 100.", "example": 1, "nullable": true }, "cursor": { "type": "string", "description": "", "example": "architecto", "nullable": true }, "search": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "n", "nullable": true }, "status": { "type": "string", "description": "", "example": "pending", "enum": [ "pending", "processing", "succeeded", "failed", "cancelled" ], "nullable": true }, "date_from": { "type": "string", "description": "Must be a valid date.", "example": "2026-07-25T10:10:46", "nullable": true }, "date_to": { "type": "string", "description": "Must be a valid date. Must be a date after or equal to date_from.", "example": "2052-08-17", "nullable": true } } } } } } }, "post": { "summary": "Create a refund.", "operationId": "createARefund", "description": "Initiates a full or partial refund for a `succeeded` payment. Refunds are asynchronous —\nlisten to the `refund.succeeded` or `refund_failed` webhooks for the final status.\nSupports idempotency via the `Idempotency-Key` header. Marketplaces can issue this refund\nfrom a connected subaccount via the `X-Sync` header.", "parameters": [], "responses": { "200": { "description": "Refund initiated", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "status": "OK", "message": "Refund initiated", "refund": { "id": "ref_01JXXX", "amount": 5000, "currency": "XAF", "status": "pending", "reason": "customer_request", "payment": "trx_01JXXX", "created_at": "2026-01-15T12:00:00Z" } }, "properties": { "code": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "OK" }, "message": { "type": "string", "example": "Refund initiated" }, "refund": { "type": "object", "properties": { "id": { "type": "string", "example": "ref_01JXXX" }, "amount": { "type": "number", "example": 5000 }, "currency": { "type": "string", "example": "XAF" }, "status": { "type": "string", "example": "pending" }, "reason": { "type": "string", "example": "customer_request" }, "payment": { "type": "string", "example": "trx_01JXXX" }, "created_at": { "type": "string", "example": "2026-01-15T12:00:00Z" } } } } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 401, "status": "Unauthorized", "message": "Invalid API credentials" }, "properties": { "code": { "type": "integer", "example": 401 }, "status": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid API credentials" } } } } } }, "406": { "description": "Private key required", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 406, "status": "Not Acceptable", "message": "Private Key Required" }, "properties": { "code": { "type": "integer", "example": 406 }, "status": { "type": "string", "example": "Not Acceptable" }, "message": { "type": "string", "example": "Private Key Required" } } } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 422, "status": "Unprocessable Content", "errors": { "payment": [ "Payment not found or cannot be refunded." ] } }, "properties": { "code": { "type": "integer", "example": 422 }, "status": { "type": "string", "example": "Unprocessable Content" }, "errors": { "type": "object", "properties": { "payment": { "type": "array", "example": [ "Payment not found or cannot be refunded." ], "items": { "type": "string" } } } } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 429, "status": "Too Many Requests" }, "properties": { "code": { "type": "integer", "example": 429 }, "status": { "type": "string", "example": "Too Many Requests" } } } } } } }, "tags": [ "Refunds" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "type": "string", "description": "", "example": "architecto" }, "amount": { "type": "number", "description": "Must be at least 0.01.", "example": 39, "nullable": true }, "currency": { "type": "string", "description": "Must be 3 characters.", "example": "gzm", "nullable": true }, "reason": { "type": "string", "description": "", "example": "architecto" }, "reference": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "n", "nullable": true }, "metadata": { "type": "object", "description": "", "example": null, "properties": {}, "nullable": true } }, "required": [ "payment", "reason" ] } } } } } }, "/refunds/{id}": { "get": { "summary": "Retrieve a refund.", "operationId": "retrieveARefund", "description": "", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "refund": { "id": "ref_01JXXX", "amount": 5000, "status": "completed" } }, "properties": { "code": { "type": "integer", "example": 200 }, "refund": { "type": "object", "properties": { "id": { "type": "string", "example": "ref_01JXXX" }, "amount": { "type": "integer", "example": 5000 }, "status": { "type": "string", "example": "completed" } } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 404 }, "properties": { "code": { "type": "integer", "example": 404 } } } } } } }, "tags": [ "Refunds" ] }, "parameters": [ { "in": "path", "name": "id", "description": "", "example": "architecto", "required": true, "schema": { "type": "string" } } ] }, "/transfers": { "get": { "summary": "List transfers.", "operationId": "listTransfers", "description": "Returns a paginated list of outgoing transfer payouts.", "parameters": [], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "status": "OK", "message": "Transfers retrieved", "items": [ { "id": "po_01JXXX", "reference": "N7vW4mX1kQ8", "amount": 10000, "currency": "XAF", "status": "succeeded", "complete": true } ], "meta": { "current_page": 1, "last_page": 2, "per_page": 25, "total": 18 } }, "properties": { "code": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "OK" }, "message": { "type": "string", "example": "Transfers retrieved" }, "items": { "type": "array", "example": [ { "id": "po_01JXXX", "reference": "N7vW4mX1kQ8", "amount": 10000, "currency": "XAF", "status": "succeeded", "complete": true } ], "items": { "type": "object", "properties": { "id": { "type": "string", "example": "po_01JXXX" }, "reference": { "type": "string", "example": "N7vW4mX1kQ8" }, "amount": { "type": "number", "example": 10000 }, "currency": { "type": "string", "example": "XAF" }, "status": { "type": "string", "example": "succeeded" }, "complete": { "type": "boolean", "example": true } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 2 }, "per_page": { "type": "integer", "example": 25 }, "total": { "type": "integer", "example": 18 } } } } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 401, "status": "Unauthorized", "message": "Invalid API credentials" }, "properties": { "code": { "type": "integer", "example": 401 }, "status": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid API credentials" } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 429, "status": "Too Many Requests" }, "properties": { "code": { "type": "integer", "example": 429 }, "status": { "type": "string", "example": "Too Many Requests" } } } } } } }, "tags": [ "Transfers" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "per_page": { "type": "integer", "description": "Must be at least 1. Must not be greater than 100.", "example": 1, "nullable": true }, "search": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "n", "nullable": true }, "status": { "type": "string", "description": "", "example": "cancelled", "enum": [ "pending", "processing", "succeeded", "failed", "cancelled" ], "nullable": true } } } } } } }, "post": { "summary": "Create a transfer.", "operationId": "createATransfer", "description": "Initiates a payout to a Mobile Money wallet or bank account. Requires a secret key\nand sufficient available balance. Transfers are asynchronous — listen to\n`transfer.succeeded` or `transfer.failed` webhooks for the final status.\nMarketplaces can pay out on behalf of a connected subaccount via the `X-Sync` header.", "parameters": [], "responses": { "202": { "description": "Transfer initiated", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 202, "status": "Accepted", "message": "Transfer initiated", "transfer": { "id": "po_01JXXX", "reference": "N7vW4mX1kQ8", "amount": 10000, "currency": "XAF", "status": "pending", "complete": false, "created_at": "2026-01-15T14:00:00Z" } }, "properties": { "code": { "type": "integer", "example": 202 }, "status": { "type": "string", "example": "Accepted" }, "message": { "type": "string", "example": "Transfer initiated" }, "transfer": { "type": "object", "properties": { "id": { "type": "string", "example": "po_01JXXX" }, "reference": { "type": "string", "example": "N7vW4mX1kQ8" }, "amount": { "type": "number", "example": 10000 }, "currency": { "type": "string", "example": "XAF" }, "status": { "type": "string", "example": "pending" }, "complete": { "type": "boolean", "example": false }, "created_at": { "type": "string", "example": "2026-01-15T14:00:00Z" } } } } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 401, "status": "Unauthorized", "message": "Invalid API credentials" }, "properties": { "code": { "type": "integer", "example": 401 }, "status": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid API credentials" } } } } } }, "406": { "description": "Private key required", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 406, "status": "Not Acceptable", "message": "Private Key Required" }, "properties": { "code": { "type": "integer", "example": 406 }, "status": { "type": "string", "example": "Not Acceptable" }, "message": { "type": "string", "example": "Private Key Required" } } } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 422, "status": "Unprocessable Content", "errors": { "amount": [ "The amount field is required." ] } }, "properties": { "code": { "type": "integer", "example": 422 }, "status": { "type": "string", "example": "Unprocessable Content" }, "errors": { "type": "object", "properties": { "amount": { "type": "array", "example": [ "The amount field is required." ], "items": { "type": "string" } } } } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 429, "status": "Too Many Requests" }, "properties": { "code": { "type": "integer", "example": 429 }, "status": { "type": "string", "example": "Too Many Requests" } } } } } } }, "tags": [ "Transfers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "beneficiary": { "type": "string", "description": "", "example": "architecto" }, "amount": { "type": "number", "description": "Must be at least 0.01.", "example": 39 }, "currency": { "type": "string", "description": "Must match an existing stored value. Must be 3 characters.", "example": "gzm", "nullable": true }, "description": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "Et fugiat sunt nihil accusantium.", "nullable": true }, "reason": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "n", "nullable": true }, "reference": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "i", "nullable": true }, "metadata": { "type": "object", "description": "", "example": null, "properties": {}, "nullable": true } }, "required": [ "beneficiary", "amount" ] } } } } } }, "/transfers/{id}": { "get": { "summary": "Retrieve a transfer.", "operationId": "retrieveATransfer", "description": "Returns a single transfer payout by its identifier.", "parameters": [], "responses": { "200": { "description": "Transfer retrieved", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "status": "OK", "message": "Transfer retrieved", "transfer": { "id": "po_01JXXX", "reference": "N7vW4mX1kQ8", "amount": 10000, "currency": "XAF", "status": "succeeded", "complete": true } }, "properties": { "code": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "OK" }, "message": { "type": "string", "example": "Transfer retrieved" }, "transfer": { "type": "object", "properties": { "id": { "type": "string", "example": "po_01JXXX" }, "reference": { "type": "string", "example": "N7vW4mX1kQ8" }, "amount": { "type": "number", "example": 10000 }, "currency": { "type": "string", "example": "XAF" }, "status": { "type": "string", "example": "succeeded" }, "complete": { "type": "boolean", "example": true } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 404, "status": "Not Found", "message": "Transfer Not Found" }, "properties": { "code": { "type": "integer", "example": 404 }, "status": { "type": "string", "example": "Not Found" }, "message": { "type": "string", "example": "Transfer Not Found" } } } } } } }, "tags": [ "Transfers" ] }, "parameters": [ { "in": "path", "name": "id", "description": "", "example": "architecto", "required": true, "schema": { "type": "string" } } ] }, "/customers": { "get": { "summary": "List customers.", "operationId": "listCustomers", "description": "", "parameters": [], "responses": { "200": { "description": "Customers list", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "status": "OK", "message": "Customers retrieved", "items": [ { "id": "cus_01JXXX", "email": "amina@example.com", "name": "Amina Diallo" } ], "meta": { "current_page": 1, "last_page": 16, "per_page": 25, "total": 156 } }, "properties": { "code": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "OK" }, "message": { "type": "string", "example": "Customers retrieved" }, "items": { "type": "array", "example": [ { "id": "cus_01JXXX", "email": "amina@example.com", "name": "Amina Diallo" } ], "items": { "type": "object", "properties": { "id": { "type": "string", "example": "cus_01JXXX" }, "email": { "type": "string", "example": "amina@example.com" }, "name": { "type": "string", "example": "Amina Diallo" } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 16 }, "per_page": { "type": "integer", "example": 25 }, "total": { "type": "integer", "example": 156 } } } } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 401 }, "properties": { "code": { "type": "integer", "example": 401 } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 429 }, "properties": { "code": { "type": "integer", "example": 429 } } } } } } }, "tags": [ "Customers" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "per_page": { "type": "integer", "description": "Must be at least 1. Must not be greater than 100.", "example": 1, "nullable": true }, "cursor": { "type": "string", "description": "", "example": "architecto", "nullable": true }, "search": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "n", "nullable": true }, "type": { "type": "string", "description": "", "example": "individual", "enum": [ "individual", "business" ], "nullable": true }, "status": { "type": "string", "description": "", "example": "blocked", "enum": [ "active", "inactive", "blocked" ], "nullable": true }, "country": { "type": "string", "description": "Must be 2 characters.", "example": "gz", "nullable": true }, "customer_group": { "type": "string", "description": "", "example": "architecto", "nullable": true } } } } } } }, "post": { "summary": "Create a customer.", "operationId": "createACustomer", "description": "Creates a reusable customer profile. At least one of `email` or `phone` is required.\nMarketplaces can create this customer under a connected subaccount via the `X-Sync` header.", "parameters": [], "responses": { "201": { "description": "Customer created", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 201, "status": "Created", "message": "Customer created", "customer": { "id": "cus_01JXXX", "email": "amina@example.com", "name": "Amina Diallo", "status": "active" } }, "properties": { "code": { "type": "integer", "example": 201 }, "status": { "type": "string", "example": "Created" }, "message": { "type": "string", "example": "Customer created" }, "customer": { "type": "object", "properties": { "id": { "type": "string", "example": "cus_01JXXX" }, "email": { "type": "string", "example": "amina@example.com" }, "name": { "type": "string", "example": "Amina Diallo" }, "status": { "type": "string", "example": "active" } } } } } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 422, "errors": { "email": [ "This customer already exists." ] } }, "properties": { "code": { "type": "integer", "example": 422 }, "errors": { "type": "object", "properties": { "email": { "type": "array", "example": [ "This customer already exists." ], "items": { "type": "string" } } } } } } } } } }, "tags": [ "Customers" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "", "example": "business", "enum": [ "individual", "business" ], "nullable": true }, "email": { "type": "string", "description": "This field is required when phone is not present. Must be a valid email address. Must not be greater than 255 characters.", "example": "gbailey@example.net", "nullable": true }, "phone": { "type": "string", "description": "This field is required when email is not present. Must not be greater than 50 characters.", "example": "m", "nullable": true }, "phone_country": { "type": "string", "description": "Must be 2 characters.", "example": "iy", "nullable": true }, "name": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "v", "nullable": true }, "company_name": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "d", "nullable": true }, "first_name": { "type": "string", "description": "", "example": null }, "last_name": { "type": "string", "description": "", "example": null }, "date_of_birth": { "type": "string", "description": "Must be a valid date. Must be a date before today.", "example": "2022-08-18", "nullable": true }, "gender": { "type": "string", "description": "", "example": "female", "enum": [ "male", "female", "other" ], "nullable": true }, "business_name": { "type": "string", "description": "This field is required when type is business. Must not be greater than 255 characters.", "example": "n", "nullable": true }, "business_type": { "type": "string", "description": "Must not be greater than 128 characters.", "example": "g", "nullable": true }, "business_registration_number": { "type": "string", "description": "Must not be greater than 64 characters.", "example": "z", "nullable": true }, "tax_id": { "type": "string", "description": "Must not be greater than 64 characters.", "example": "m", "nullable": true }, "legal_representative_name": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "i", "nullable": true }, "legal_representative_title": { "type": "string", "description": "Must not be greater than 128 characters.", "example": "y", "nullable": true }, "description": { "type": "string", "description": "Must not be greater than 1000 characters.", "example": "Sunt nihil accusantium harum mollitia.", "nullable": true }, "notes": { "type": "string", "description": "", "example": "architecto", "nullable": true }, "currency": { "type": "string", "description": "Must be 3 characters.", "example": "ngz", "nullable": true }, "address": { "type": "object", "description": "", "example": null, "properties": { "country": { "type": "string", "description": "Must be 2 characters.", "example": "mi", "nullable": true }, "city": { "type": "string", "description": "Must not be greater than 128 characters.", "example": "y", "nullable": true }, "address_line1": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "v", "nullable": true }, "state": { "type": "string", "description": "Must not be greater than 128 characters.", "example": "d", "nullable": true }, "postal_code": { "type": "string", "description": "Must not be greater than 20 characters.", "example": "ljnikhwaykcmyuwp", "nullable": true }, "address_line2": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "w", "nullable": true } }, "nullable": true }, "billing": { "type": "object", "description": "", "example": null, "properties": { "country": { "type": "string", "description": "Must be 2 characters.", "example": "lv", "nullable": true }, "city": { "type": "string", "description": "Must not be greater than 128 characters.", "example": "q", "nullable": true }, "address_line1": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "w", "nullable": true }, "state": { "type": "string", "description": "Must not be greater than 128 characters.", "example": "r", "nullable": true }, "postal_code": { "type": "string", "description": "Must not be greater than 20 characters.", "example": "sitcpscqldzsnrwt", "nullable": true }, "address_line2": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "u", "nullable": true } }, "nullable": true }, "preferred_language": { "type": "string", "description": "Must not be greater than 10 characters.", "example": "jwvlxj", "nullable": true }, "preferred_currencies": { "type": "array", "description": "Must be 3 characters.", "example": [ "klq" ], "items": { "type": "string" } }, "preferred_locales": { "type": "array", "description": "Must not be greater than 10 characters.", "example": [ "ppwqbe" ], "items": { "type": "string" } }, "customer_group": { "type": "string", "description": "Must not be greater than 64 characters.", "example": "w", "nullable": true }, "tags": { "type": "array", "description": "Must not be greater than 50 characters.", "example": [ "t" ], "items": { "type": "string" } }, "metadata": { "type": "object", "description": "", "example": null, "properties": {}, "nullable": true } } } } } } } }, "/customers/{id}": { "get": { "summary": "Retrieve a customer.", "operationId": "retrieveACustomer", "description": "", "parameters": [], "responses": { "200": { "description": "Customer retrieved", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "status": "OK", "message": "Customer retrieved", "customer": { "id": "cus_01JXXX", "email": "amina@example.com", "name": "Amina Diallo", "status": "active" } }, "properties": { "code": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "OK" }, "message": { "type": "string", "example": "Customer retrieved" }, "customer": { "type": "object", "properties": { "id": { "type": "string", "example": "cus_01JXXX" }, "email": { "type": "string", "example": "amina@example.com" }, "name": { "type": "string", "example": "Amina Diallo" }, "status": { "type": "string", "example": "active" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 404 }, "properties": { "code": { "type": "integer", "example": 404 } } } } } } }, "tags": [ "Customers" ] }, "put": { "summary": "Update a customer.", "operationId": "updateACustomer", "description": "", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "status": "OK", "message": "Customer updated", "customer": { "id": "cus_01JXXXXXXXXXXXXX" } }, "properties": { "code": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "OK" }, "message": { "type": "string", "example": "Customer updated" }, "customer": { "type": "object", "properties": { "id": { "type": "string", "example": "cus_01JXXXXXXXXXXXXX" } } } } } } } } }, "tags": [ "Customers" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Must be a valid email address. Must not be greater than 255 characters.", "example": "gbailey@example.net", "nullable": true }, "phone": { "type": "string", "description": "Must not be greater than 50 characters.", "example": "m", "nullable": true }, "phone_country": { "type": "string", "description": "Must be 2 characters.", "example": "iy", "nullable": true }, "name": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "v", "nullable": true }, "company_name": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "d", "nullable": true }, "first_name": { "type": "string", "description": "", "example": null }, "last_name": { "type": "string", "description": "", "example": null }, "date_of_birth": { "type": "string", "description": "Must be a valid date. Must be a date before today.", "example": "2022-08-18", "nullable": true }, "gender": { "type": "string", "description": "", "example": "male", "enum": [ "male", "female", "other" ], "nullable": true }, "business_name": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "n", "nullable": true }, "business_type": { "type": "string", "description": "Must not be greater than 128 characters.", "example": "g", "nullable": true }, "business_registration_number": { "type": "string", "description": "Must not be greater than 64 characters.", "example": "z", "nullable": true }, "tax_id": { "type": "string", "description": "Must not be greater than 64 characters.", "example": "m", "nullable": true }, "legal_representative_name": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "i", "nullable": true }, "legal_representative_title": { "type": "string", "description": "Must not be greater than 128 characters.", "example": "y", "nullable": true }, "description": { "type": "string", "description": "Must not be greater than 1000 characters.", "example": "Sunt nihil accusantium harum mollitia.", "nullable": true }, "notes": { "type": "string", "description": "", "example": "architecto", "nullable": true }, "currency": { "type": "string", "description": "Must be 3 characters.", "example": "ngz", "nullable": true }, "address": { "type": "object", "description": "", "example": null, "properties": { "country": { "type": "string", "description": "Must be 2 characters.", "example": "mi", "nullable": true }, "city": { "type": "string", "description": "Must not be greater than 128 characters.", "example": "y", "nullable": true }, "address_line1": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "v", "nullable": true }, "state": { "type": "string", "description": "Must not be greater than 128 characters.", "example": "d", "nullable": true }, "postal_code": { "type": "string", "description": "Must not be greater than 20 characters.", "example": "ljnikhwaykcmyuwp", "nullable": true }, "address_line2": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "w", "nullable": true } }, "nullable": true }, "billing": { "type": "object", "description": "", "example": null, "properties": { "country": { "type": "string", "description": "Must be 2 characters.", "example": "lv", "nullable": true }, "city": { "type": "string", "description": "Must not be greater than 128 characters.", "example": "q", "nullable": true }, "address_line1": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "w", "nullable": true }, "state": { "type": "string", "description": "Must not be greater than 128 characters.", "example": "r", "nullable": true }, "postal_code": { "type": "string", "description": "Must not be greater than 20 characters.", "example": "sitcpscqldzsnrwt", "nullable": true }, "address_line2": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "u", "nullable": true } }, "nullable": true }, "preferred_language": { "type": "string", "description": "Must not be greater than 10 characters.", "example": "jwvlxj", "nullable": true }, "preferred_currencies": { "type": "array", "description": "Must be 3 characters.", "example": [ "klq" ], "items": { "type": "string" } }, "preferred_locales": { "type": "array", "description": "Must not be greater than 10 characters.", "example": [ "ppwqbe" ], "items": { "type": "string" } }, "customer_group": { "type": "string", "description": "Must not be greater than 64 characters.", "example": "w", "nullable": true }, "tags": { "type": "array", "description": "Must not be greater than 50 characters.", "example": [ "t" ], "items": { "type": "string" } }, "metadata": { "type": "object", "description": "", "example": null, "properties": {}, "nullable": true } } } } } } }, "delete": { "summary": "Delete a customer.", "operationId": "deleteACustomer", "description": "", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "status": "OK", "message": "Customer archived" }, "properties": { "code": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "OK" }, "message": { "type": "string", "example": "Customer archived" } } } } } } }, "tags": [ "Customers" ] }, "parameters": [ { "in": "path", "name": "id", "description": "", "example": "architecto", "required": true, "schema": { "type": "string" } } ] }, "/beneficiaries": { "get": { "summary": "List beneficiaries.", "operationId": "listBeneficiaries", "description": "", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "items": [], "meta": { "total": 0 } }, "properties": { "code": { "type": "integer", "example": 200 }, "items": { "type": "array", "example": [] }, "meta": { "type": "object", "properties": { "total": { "type": "integer", "example": 0 } } } } } } } } }, "tags": [ "Beneficiaries" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "per_page": { "type": "integer", "description": "Must be at least 1. Must not be greater than 100.", "example": 1, "nullable": true }, "cursor": { "type": "string", "description": "", "example": "architecto", "nullable": true }, "search": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "n", "nullable": true }, "is_active": { "type": "boolean", "description": "", "example": false, "nullable": true } } } } } } }, "post": { "summary": "Create a beneficiary.", "operationId": "createABeneficiary", "description": "Save a recipient for reuse in transfers. Supports Mobile Money wallets and bank accounts.", "parameters": [], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 201, "beneficiary": { "id": "bfn_01JXXX", "name": "Jean Dupont", "channel": "cm.mtn" } }, "properties": { "code": { "type": "integer", "example": 201 }, "beneficiary": { "type": "object", "properties": { "id": { "type": "string", "example": "bfn_01JXXX" }, "name": { "type": "string", "example": "Jean Dupont" }, "channel": { "type": "string", "example": "cm.mtn" } } } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 422, "errors": {} }, "properties": { "code": { "type": "integer", "example": 422 }, "errors": { "type": "object", "properties": {} } } } } } } }, "tags": [ "Beneficiaries" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string", "description": "", "example": "architecto" }, "name": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "n" }, "account_number": { "type": "string", "description": "Must not be greater than 50 characters.", "example": "g", "nullable": true }, "phone": { "type": "string", "description": "Must not be greater than 20 characters.", "example": "zmiyvdljnikhwayk", "nullable": true }, "email": { "type": "string", "description": "Must be a valid email address. Must not be greater than 255 characters.", "example": "lyric80@example.com", "nullable": true }, "country_code": { "type": "string", "description": "Must be 2 characters.", "example": "pw", "nullable": true }, "note": { "type": "string", "description": "Must not be greater than 1000 characters.", "example": "l", "nullable": true }, "metadata": { "type": "object", "description": "", "example": null, "properties": {}, "nullable": true }, "iban": { "type": "string", "description": "Must not be greater than 34 characters.", "example": "v", "nullable": true }, "swift": { "type": "string", "description": "Must not be greater than 11 characters.", "example": "qwrsit", "nullable": true }, "vault": { "type": "object", "description": "", "example": null, "properties": {}, "nullable": true }, "vault_type": { "type": "string", "description": "Must not be greater than 50 characters.", "example": "c", "nullable": true }, "vault_details": { "type": "object", "description": "", "example": null, "properties": {}, "nullable": true }, "vault_holder_name": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "p", "nullable": true }, "vault_last_four": { "type": "string", "description": "Must be 4 characters.", "example": "scql", "nullable": true }, "vault_phone_number": { "type": "string", "description": "Must not be greater than 20 characters.", "example": "dzsnrwtujwvlxjkl", "nullable": true }, "vault_bank_code": { "type": "string", "description": "Must not be greater than 20 characters.", "example": "qppwqbewtnnoqitp", "nullable": true }, "vault_account_type": { "type": "string", "description": "Must not be greater than 20 characters.", "example": "xntltcvipojsausg", "nullable": true }, "vault_operator": { "type": "string", "description": "Must not be greater than 50 characters.", "example": "i", "nullable": true } }, "required": [ "channel", "name" ] } } } } } }, "/beneficiaries/{id}": { "get": { "summary": "Retrieve a beneficiary.", "operationId": "retrieveABeneficiary", "description": "", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "beneficiary": { "id": "bfn_01JXXX", "name": "Jean Dupont" } }, "properties": { "code": { "type": "integer", "example": 200 }, "beneficiary": { "type": "object", "properties": { "id": { "type": "string", "example": "bfn_01JXXX" }, "name": { "type": "string", "example": "Jean Dupont" } } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 404 }, "properties": { "code": { "type": "integer", "example": 404 } } } } } } }, "tags": [ "Beneficiaries" ] }, "put": { "summary": "Update a beneficiary.", "operationId": "updateABeneficiary", "description": "", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "beneficiary": { "id": "bfn_01JXXX" } }, "properties": { "code": { "type": "integer", "example": 200 }, "beneficiary": { "type": "object", "properties": { "id": { "type": "string", "example": "bfn_01JXXX" } } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 404 }, "properties": { "code": { "type": "integer", "example": 404 } } } } } } }, "tags": [ "Beneficiaries" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "b" }, "email": { "type": "string", "description": "Must be a valid email address. Must not be greater than 255 characters.", "example": "zbailey@example.net", "nullable": true }, "phone": { "type": "string", "description": "Must not be greater than 32 characters.", "example": "i", "nullable": true }, "country_code": { "type": "string", "description": "Must be 2 characters.", "example": "yv", "nullable": true }, "metadata": { "type": "object", "description": "", "example": null, "properties": {}, "nullable": true } } } } } } }, "delete": { "summary": "Delete a beneficiary.", "operationId": "deleteABeneficiary", "description": "Soft-deletes the beneficiary. It is removed from future transfer suggestions.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "message": "Beneficiary deleted" }, "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Beneficiary deleted" } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 404 }, "properties": { "code": { "type": "integer", "example": 404 } } } } } } }, "tags": [ "Beneficiaries" ] }, "parameters": [ { "in": "path", "name": "id", "description": "", "example": "architecto", "required": true, "schema": { "type": "string" } } ] }, "/balance": { "get": { "summary": "Retrieve balance.", "operationId": "retrieveBalance", "description": "Returns the available, pending and reserved balance held by our licensed payment partner.\nRequires a **secret key**. Cached for 3 minutes for performance — poll before each transfer batch.", "parameters": [], "responses": { "200": { "description": "Balance retrieved", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "status": "OK", "message": "Balance retrieved", "balance": { "total": 1325000, "available": 1250000, "pending": 75000, "reserved": 0, "credit": 0, "currency": "XAF", "environment": "live" } }, "properties": { "code": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "OK" }, "message": { "type": "string", "example": "Balance retrieved" }, "balance": { "type": "object", "properties": { "total": { "type": "integer", "example": 1325000 }, "available": { "type": "integer", "example": 1250000 }, "pending": { "type": "integer", "example": 75000 }, "reserved": { "type": "integer", "example": 0 }, "credit": { "type": "integer", "example": 0 }, "currency": { "type": "string", "example": "XAF" }, "environment": { "type": "string", "example": "live" } } } } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 401, "status": "Unauthorized", "message": "Invalid API credentials" }, "properties": { "code": { "type": "integer", "example": 401 }, "status": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid API credentials" } } } } } }, "406": { "description": "Private key required", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 406, "status": "Not Acceptable", "message": "Private Key Required" }, "properties": { "code": { "type": "integer", "example": 406 }, "status": { "type": "string", "example": "Not Acceptable" }, "message": { "type": "string", "example": "Private Key Required" } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 429, "status": "Too Many Requests" }, "properties": { "code": { "type": "integer", "example": 429 }, "status": { "type": "string", "example": "Too Many Requests" } } } } } } }, "tags": [ "Balance" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "description": "Must be 3 characters.", "example": "bng", "nullable": true } } } } } } } }, "/events": { "get": { "summary": "List events.", "operationId": "listEvents", "description": "Returns a paginated list of webhook events linked to your account.\nUse this to replay events, audit activity, or debug failed deliveries.", "parameters": [], "responses": { "200": { "description": "Events list", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "status": "OK", "message": "Events retrieved", "events": [ { "id": "evt_01JXXX", "type": "payment.succeeded", "data": { "reference": "trx.PVrU8x2kQ1", "status": "succeeded" }, "created_at": "2026-01-15T10:31:00Z" } ], "meta": { "current_page": 1, "last_page": 9, "per_page": 25, "total": 328 } }, "properties": { "code": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "OK" }, "message": { "type": "string", "example": "Events retrieved" }, "events": { "type": "array", "example": [ { "id": "evt_01JXXX", "type": "payment.succeeded", "data": { "reference": "trx.PVrU8x2kQ1", "status": "succeeded" }, "created_at": "2026-01-15T10:31:00Z" } ], "items": { "type": "object", "properties": { "id": { "type": "string", "example": "evt_01JXXX" }, "type": { "type": "string", "example": "payment.succeeded" }, "data": { "type": "object", "properties": { "reference": { "type": "string", "example": "trx.PVrU8x2kQ1" }, "status": { "type": "string", "example": "succeeded" } } }, "created_at": { "type": "string", "example": "2026-01-15T10:31:00Z" } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 9 }, "per_page": { "type": "integer", "example": 25 }, "total": { "type": "integer", "example": 328 } } } } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 401 }, "properties": { "code": { "type": "integer", "example": 401 } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 429 }, "properties": { "code": { "type": "integer", "example": 429 } } } } } } }, "tags": [ "Events" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "per_page": { "type": "integer", "description": "Must be at least 1. Must not be greater than 100.", "example": 1, "nullable": true }, "page": { "type": "integer", "description": "Must be at least 1.", "example": 22, "nullable": true }, "type": { "type": "string", "description": "Must not be greater than 128 characters.", "example": "g", "nullable": true } } } } } } } }, "/events/{id}": { "get": { "summary": "Retrieve an event.", "operationId": "retrieveAnEvent", "description": "Returns a single event by its identifier.", "parameters": [], "responses": { "200": { "description": "Event retrieved", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "status": "OK", "event": { "id": "evt_01JXXX", "type": "payment.succeeded", "created_at": "2026-01-15T10:31:00Z" } }, "properties": { "code": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "OK" }, "event": { "type": "object", "properties": { "id": { "type": "string", "example": "evt_01JXXX" }, "type": { "type": "string", "example": "payment.succeeded" }, "created_at": { "type": "string", "example": "2026-01-15T10:31:00Z" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 404 }, "properties": { "code": { "type": "integer", "example": 404 } } } } } } }, "tags": [ "Events" ] }, "parameters": [ { "in": "path", "name": "id", "description": "", "example": "architecto", "required": true, "schema": { "type": "string" } } ] }, "/events/{id}/resend": { "post": { "summary": "Resend an event.", "operationId": "resendAnEvent", "description": "Re-queues an event for delivery to all active webhook endpoints.\nUseful for replaying failed or missed deliveries.\nInternal `transaction.*` events cannot be resent.", "parameters": [], "responses": { "202": { "description": "Queued", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 202, "status": "Accepted", "message": "Event re-delivery queued." }, "properties": { "code": { "type": "integer", "example": 202 }, "status": { "type": "string", "example": "Accepted" }, "message": { "type": "string", "example": "Event re-delivery queued." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 404, "status": "Not Found" }, "properties": { "code": { "type": "integer", "example": 404 }, "status": { "type": "string", "example": "Not Found" } } } } } }, "422": { "description": "Internal event", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 422, "status": "Unprocessable Content", "message": "Internal events cannot be resent." }, "properties": { "code": { "type": "integer", "example": 422 }, "status": { "type": "string", "example": "Unprocessable Content" }, "message": { "type": "string", "example": "Internal events cannot be resent." } } } } } } }, "tags": [ "Events" ] }, "parameters": [ { "in": "path", "name": "id", "description": "", "example": "architecto", "required": true, "schema": { "type": "string" } } ] }, "/webhooks": { "get": { "summary": "List webhook endpoints.", "operationId": "listWebhookEndpoints", "description": "", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "items": [], "meta": { "total": 0 } }, "properties": { "code": { "type": "integer", "example": 200 }, "items": { "type": "array", "example": [] }, "meta": { "type": "object", "properties": { "total": { "type": "integer", "example": 0 } } } } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 401 }, "properties": { "code": { "type": "integer", "example": 401 } } } } } } }, "tags": [ "Webhook Endpoints" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "per_page": { "type": "integer", "description": "Must be at least 1. Must not be greater than 100.", "example": 1, "nullable": true }, "cursor": { "type": "string", "description": "", "example": "architecto", "nullable": true }, "search": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "n", "nullable": true } } } } } } }, "post": { "summary": "Create a webhook endpoint.", "operationId": "createAWebhookEndpoint", "description": "Subscribe to one or more event types. Wajub sends a signed `POST` request\nto your URL each time a matching event fires.", "parameters": [], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 201, "endpoint": { "id": "wh_01JXXX", "url": "https://example.com/webhooks/wajub", "secret": "whsec_…", "events": [ "payment.succeeded" ] } }, "properties": { "code": { "type": "integer", "example": 201 }, "endpoint": { "type": "object", "properties": { "id": { "type": "string", "example": "wh_01JXXX" }, "url": { "type": "string", "example": "https://example.com/webhooks/wajub" }, "secret": { "type": "string", "example": "whsec_…" }, "events": { "type": "array", "example": [ "payment.succeeded" ], "items": { "type": "string" } } } } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 422, "errors": { "url": [ "The url must be a valid URL." ] } }, "properties": { "code": { "type": "integer", "example": 422 }, "errors": { "type": "object", "properties": { "url": { "type": "array", "example": [ "The url must be a valid URL." ], "items": { "type": "string" } } } } } } } } } }, "tags": [ "Webhook Endpoints" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Must be a valid URL. Must not be greater than 2048 characters.", "example": "http://www.bailey.biz/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html" }, "events": { "type": "array", "description": "Must not be greater than 100 characters.", "example": [ "i" ], "items": { "type": "string" } }, "description": { "type": "string", "description": "Must not be greater than 500 characters.", "example": "Deserunt aut ab provident perspiciatis quo omnis nostrum.", "nullable": true } }, "required": [ "url" ] } } } } } }, "/webhooks/{id}": { "get": { "summary": "Retrieve a webhook endpoint.", "operationId": "retrieveAWebhookEndpoint", "description": "", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "endpoint": { "id": "wh_01JXXX", "url": "https://example.com/webhook", "events": [ "payment.succeeded" ] } }, "properties": { "code": { "type": "integer", "example": 200 }, "endpoint": { "type": "object", "properties": { "id": { "type": "string", "example": "wh_01JXXX" }, "url": { "type": "string", "example": "https://example.com/webhook" }, "events": { "type": "array", "example": [ "payment.succeeded" ], "items": { "type": "string" } } } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 404 }, "properties": { "code": { "type": "integer", "example": 404 } } } } } } }, "tags": [ "Webhook Endpoints" ] }, "put": { "summary": "Update a webhook endpoint.", "operationId": "updateAWebhookEndpoint", "description": "", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "endpoint": { "id": "wh_01JXXX" } }, "properties": { "code": { "type": "integer", "example": 200 }, "endpoint": { "type": "object", "properties": { "id": { "type": "string", "example": "wh_01JXXX" } } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 404 }, "properties": { "code": { "type": "integer", "example": 404 } } } } } } }, "tags": [ "Webhook Endpoints" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Must be a valid URL. Must not be greater than 2048 characters.", "example": "http://www.bailey.biz/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html", "nullable": true }, "events": { "type": "array", "description": "Must not be greater than 100 characters.", "example": [ "i" ], "items": { "type": "string" } }, "description": { "type": "string", "description": "Must not be greater than 500 characters.", "example": "Deserunt aut ab provident perspiciatis quo omnis nostrum.", "nullable": true }, "active": { "type": "boolean", "description": "", "example": false, "nullable": true } } } } } } }, "delete": { "summary": "Delete a webhook endpoint.", "operationId": "deleteAWebhookEndpoint", "description": "", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "message": "Webhook endpoint deleted." }, "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Webhook endpoint deleted." } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 404 }, "properties": { "code": { "type": "integer", "example": 404 } } } } } } }, "tags": [ "Webhook Endpoints" ] }, "parameters": [ { "in": "path", "name": "id", "description": "The ID of the webhook.", "example": "architecto", "required": true, "schema": { "type": "string" } } ] }, "/webhooks/{id}/rotate-secret": { "post": { "summary": "Rotate webhook secret.", "operationId": "rotateWebhookSecret", "description": "Generates a new signing secret (`whsec_…`) for this endpoint. Update your\nsignature verification immediately — the old secret is invalidated.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "endpoint": { "id": "wh_01JXXX", "secret": "whsec_newvalue" } }, "properties": { "code": { "type": "integer", "example": 200 }, "endpoint": { "type": "object", "properties": { "id": { "type": "string", "example": "wh_01JXXX" }, "secret": { "type": "string", "example": "whsec_newvalue" } } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 404 }, "properties": { "code": { "type": "integer", "example": 404 } } } } } } }, "tags": [ "Webhook Endpoints" ] }, "parameters": [ { "in": "path", "name": "id", "description": "The ID of the webhook.", "example": "architecto", "required": true, "schema": { "type": "string" } } ] }, "/invoices": { "get": { "summary": "List invoices (live only, document_type = invoice).", "operationId": "listInvoicesliveOnlyDocumentTypeInvoice", "description": "", "parameters": [], "responses": { "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 401, "status": "Unauthorized", "message": "Invalid API credentials" }, "properties": { "code": { "type": "integer", "example": 401 }, "status": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid API credentials" } } } } } } }, "tags": [ "Invoices" ] }, "post": { "summary": "Create invoice (live only, invoicing plan limit).", "operationId": "createInvoiceliveOnlyInvoicingPlanLimit", "description": "", "parameters": [], "responses": { "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 401, "status": "Unauthorized", "message": "Invalid API credentials" }, "properties": { "code": { "type": "integer", "example": 401 }, "status": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid API credentials" } } } } } } }, "tags": [ "Invoices" ] } }, "/invoices/{id}": { "get": { "summary": "Retrieve an invoice.", "operationId": "retrieveAnInvoice", "description": "", "parameters": [], "responses": { "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 401, "status": "Unauthorized", "message": "Invalid API credentials" }, "properties": { "code": { "type": "integer", "example": 401 }, "status": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid API credentials" } } } } } } }, "tags": [ "Invoices" ] }, "put": { "summary": "Update invoice (only when editable).", "operationId": "updateInvoiceonlyWhenEditable", "description": "", "parameters": [], "responses": { "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 401, "status": "Unauthorized", "message": "Invalid API credentials" }, "properties": { "code": { "type": "integer", "example": 401 }, "status": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid API credentials" } } } } } } }, "tags": [ "Invoices" ] }, "delete": { "summary": "Delete invoice (only when editable).", "operationId": "deleteInvoiceonlyWhenEditable", "description": "", "parameters": [], "responses": { "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 401, "status": "Unauthorized", "message": "Invalid API credentials" }, "properties": { "code": { "type": "integer", "example": 401 }, "status": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid API credentials" } } } } } } }, "tags": [ "Invoices" ] }, "parameters": [ { "in": "path", "name": "id", "description": "", "example": "architecto", "required": true, "schema": { "type": "string" } } ] }, "/invoices/{id}/send": { "post": { "summary": "Mark invoice as sent.", "operationId": "markInvoiceAsSent", "description": "", "parameters": [], "responses": { "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 401, "status": "Unauthorized", "message": "Invalid API credentials" }, "properties": { "code": { "type": "integer", "example": 401 }, "status": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid API credentials" } } } } } } }, "tags": [ "Invoices" ] }, "parameters": [ { "in": "path", "name": "id", "description": "", "example": "architecto", "required": true, "schema": { "type": "string" } } ] }, "/invoices/{id}/mark-paid": { "post": { "summary": "Mark invoice as paid (full or partial).", "operationId": "markInvoiceAsPaidfullOrPartial", "description": "", "parameters": [], "responses": { "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 401, "status": "Unauthorized", "message": "Invalid API credentials" }, "properties": { "code": { "type": "integer", "example": 401 }, "status": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid API credentials" } } } } } } }, "tags": [ "Invoices" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Must be at least 0.", "example": 27, "nullable": true }, "transaction_id": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "n", "nullable": true }, "payment_date": { "type": "string", "description": "Must be a valid date.", "example": "2026-07-25T10:10:46", "nullable": true }, "payment_method": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "g", "nullable": true }, "notes": { "type": "string", "description": "Must not be greater than 1000 characters.", "example": "z", "nullable": true } } } } } } }, "parameters": [ { "in": "path", "name": "id", "description": "", "example": "architecto", "required": true, "schema": { "type": "string" } } ] }, "/invoices/{id}/cancel": { "post": { "summary": "Cancel invoice.", "operationId": "cancelInvoice", "description": "", "parameters": [], "responses": { "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 401, "status": "Unauthorized", "message": "Invalid API credentials" }, "properties": { "code": { "type": "integer", "example": 401 }, "status": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid API credentials" } } } } } } }, "tags": [ "Invoices" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Must not be greater than 500 characters.", "example": "b", "nullable": true } } } } } } }, "parameters": [ { "in": "path", "name": "id", "description": "", "example": "architecto", "required": true, "schema": { "type": "string" } } ] }, "/links": { "get": { "summary": "List payment links.", "operationId": "listPaymentLinks", "description": "", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "items": [], "meta": { "total": 0 } }, "properties": { "code": { "type": "integer", "example": 200 }, "items": { "type": "array", "example": [] }, "meta": { "type": "object", "properties": { "total": { "type": "integer", "example": 0 } } } } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 401 }, "properties": { "code": { "type": "integer", "example": 401 } } } } } } }, "tags": [ "Payment Links" ] }, "post": { "summary": "Create a payment link.", "operationId": "createAPaymentLink", "description": "Creates a shareable payment URL. Live only. Subject to plan limits.", "parameters": [], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 201, "link": { "id": "lnk_01JXXX", "url": "https://pay.wajub.com/q/abc", "title": "Annual subscription" } }, "properties": { "code": { "type": "integer", "example": 201 }, "link": { "type": "object", "properties": { "id": { "type": "string", "example": "lnk_01JXXX" }, "url": { "type": "string", "example": "https://pay.wajub.com/q/abc" }, "title": { "type": "string", "example": "Annual subscription" } } } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 422, "errors": {} }, "properties": { "code": { "type": "integer", "example": 422 }, "errors": { "type": "object", "properties": {} } } } } } } }, "tags": [ "Payment Links" ] } }, "/links/{id}": { "get": { "summary": "Retrieve a payment link.", "operationId": "retrieveAPaymentLink", "description": "", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "link": { "id": "lnk_01JXXX", "url": "https://pay.wajub.com/q/abc" } }, "properties": { "code": { "type": "integer", "example": 200 }, "link": { "type": "object", "properties": { "id": { "type": "string", "example": "lnk_01JXXX" }, "url": { "type": "string", "example": "https://pay.wajub.com/q/abc" } } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 404 }, "properties": { "code": { "type": "integer", "example": 404 } } } } } } }, "tags": [ "Payment Links" ] }, "put": { "summary": "Update a payment link.", "operationId": "updateAPaymentLink", "description": "", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "link": { "id": "lnk_01JXXX" } }, "properties": { "code": { "type": "integer", "example": 200 }, "link": { "type": "object", "properties": { "id": { "type": "string", "example": "lnk_01JXXX" } } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 404 }, "properties": { "code": { "type": "integer", "example": 404 } } } } } } }, "tags": [ "Payment Links" ] }, "delete": { "summary": "Delete a payment link.", "operationId": "deleteAPaymentLink", "description": "Soft-deletes (archives) the link. The URL becomes inactive immediately.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "message": "Payment link deleted" }, "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Payment link deleted" } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 404 }, "properties": { "code": { "type": "integer", "example": 404 } } } } } } }, "tags": [ "Payment Links" ] }, "parameters": [ { "in": "path", "name": "id", "description": "", "example": "architecto", "required": true, "schema": { "type": "string" } } ] }, "/accounts": { "get": { "summary": "List subaccounts.", "operationId": "listSubaccounts", "description": "", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "items": [], "meta": { "total": 0 } }, "properties": { "code": { "type": "integer", "example": 200 }, "items": { "type": "array", "example": [] }, "meta": { "type": "object", "properties": { "total": { "type": "integer", "example": 0 } } } } } } } } }, "tags": [ "Subaccounts" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "per_page": { "type": "integer", "description": "Must be at least 1. Must not be greater than 100.", "example": 1, "nullable": true }, "cursor": { "type": "string", "description": "", "example": "architecto", "nullable": true }, "status": { "type": "string", "description": "", "example": "cancelled", "enum": [ "pending", "active", "cancelled", "expired" ], "nullable": true } } } } } } }, "post": { "summary": "Create a subaccount.", "operationId": "createASubaccount", "description": "Creates a connected subaccount for marketplace/platform use. Grant it capabilities and\noptionally configure per-account pricing (the fee your platform retains on its activity).", "parameters": [], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 201, "account": { "id": "acc_01JXXX", "reference": "shop-amina", "status": "pending" } }, "properties": { "code": { "type": "integer", "example": 201 }, "account": { "type": "object", "properties": { "id": { "type": "string", "example": "acc_01JXXX" }, "reference": { "type": "string", "example": "shop-amina" }, "status": { "type": "string", "example": "pending" } } } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 422, "errors": {} }, "properties": { "code": { "type": "integer", "example": 422 }, "errors": { "type": "object", "properties": {} } } } } } } }, "tags": [ "Subaccounts" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "description": "Must not be greater than 255 characters.", "example": "b", "nullable": true }, "capabilities": { "type": "array", "description": "", "example": [ "architecto" ], "items": { "type": "string" } }, "pricing": { "type": "object", "description": "", "example": null, "properties": { "percentage_fee": { "type": "number", "description": "Must be at least 0. Must not be greater than 100.", "example": 22, "nullable": true }, "fixed_fee": { "type": "number", "description": "Must be at least 0.", "example": 84, "nullable": true }, "max_fee": { "type": "number", "description": "Must be at least 0.", "example": 12, "nullable": true }, "min_fee": { "type": "number", "description": "Must be at least 0.", "example": 77, "nullable": true }, "currency": { "type": "string", "description": "This field is required when pricing.type is fixed. This field is required when pricing.fixed_fee, pricing.min_fee, or pricing.max_fee is present. Must be 3 characters.", "example": "iyv", "nullable": true } }, "nullable": true }, "callback": { "type": "string", "description": "Must be a valid URL. Must not be greater than 2048 characters.", "example": "d", "nullable": true }, "metadata": { "type": "object", "description": "", "example": null, "properties": {}, "nullable": true } } } } } } } }, "/accounts/{id}": { "get": { "summary": "Retrieve a subaccount.", "operationId": "retrieveASubaccount", "description": "", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "account": { "id": "sub_01JXXX", "business_name": "Boutique Fatima" } }, "properties": { "code": { "type": "integer", "example": 200 }, "account": { "type": "object", "properties": { "id": { "type": "string", "example": "sub_01JXXX" }, "business_name": { "type": "string", "example": "Boutique Fatima" } } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 404 }, "properties": { "code": { "type": "integer", "example": 404 } } } } } } }, "tags": [ "Subaccounts" ] }, "put": { "summary": "Update a subaccount.", "operationId": "updateASubaccount", "description": "", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "account": { "id": "sub_01JXXX" } }, "properties": { "code": { "type": "integer", "example": 200 }, "account": { "type": "object", "properties": { "id": { "type": "string", "example": "sub_01JXXX" } } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 404 }, "properties": { "code": { "type": "integer", "example": 404 } } } } } } }, "tags": [ "Subaccounts" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "capabilities": { "type": "array", "description": "", "example": [ "architecto" ], "items": { "type": "string" } }, "pricing": { "type": "object", "description": "", "example": null, "properties": { "percentage_fee": { "type": "number", "description": "Must be at least 0. Must not be greater than 100.", "example": 22, "nullable": true }, "fixed_fee": { "type": "number", "description": "Must be at least 0.", "example": 84, "nullable": true }, "max_fee": { "type": "number", "description": "Must be at least 0.", "example": 12, "nullable": true }, "min_fee": { "type": "number", "description": "Must be at least 0.", "example": 77, "nullable": true }, "currency": { "type": "string", "description": "This field is required when pricing.type is fixed. This field is required when pricing.fixed_fee, pricing.min_fee, or pricing.max_fee is present. Must be 3 characters.", "example": "iyv", "nullable": true } }, "nullable": true }, "callback": { "type": "string", "description": "Must be a valid URL. Must not be greater than 2048 characters.", "example": "d", "nullable": true }, "payment_status": { "type": "string", "description": "", "example": "active", "enum": [ "active", "suspended" ], "nullable": true } } } } } } }, "delete": { "summary": "Delete a subaccount.", "operationId": "deleteASubaccount", "description": "Disconnects/cancels the subaccount and revokes its tokens.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "status": "OK", "message": "Account disconnected" }, "properties": { "code": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "OK" }, "message": { "type": "string", "example": "Account disconnected" } } } } } } }, "tags": [ "Subaccounts" ] }, "parameters": [ { "in": "path", "name": "id", "description": "", "example": "architecto", "required": true, "schema": { "type": "string" } } ] }, "/accounts/{id}/token": { "post": { "summary": "Regenerate a subaccount's authorization token.", "operationId": "regenerateASubaccountsAuthorizationToken", "description": "Only allowed while the connection is not yet active.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 200, "status": "OK", "token": "..." }, "properties": { "code": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "OK" }, "token": { "type": "string", "example": "..." } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "code": 400, "status": "Bad Request", "message": "Cannot generate a new token for an active connection." }, "properties": { "code": { "type": "integer", "example": 400 }, "status": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "example": "Cannot generate a new token for an active connection." } } } } } } }, "tags": [ "Subaccounts" ] }, "parameters": [ { "in": "path", "name": "id", "description": "", "example": "architecto", "required": true, "schema": { "type": "string" } } ] } } }