{ "openapi": "3.1.0", "info": { "title": "Monerail API", "version": "2026-10-30", "description": "Collections and payouts with mobile money across Africa, and virtual Visa and Mastercard cards. Docs: https://docs.monerail.com", "contact": { "email": "support@monerail.com" } }, "servers": [ { "url": "https://api.monerail.com" } ], "security": [ { "apiKey": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "mr_test_… or mr_live_… key" } }, "schemas": { "Collection": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier (UUID)." }, "livemode": { "type": "boolean", "description": "true for live objects, false for test objects." }, "object": { "type": "string", "description": "Always collection ." }, "status": { "type": "string", "enum": [ "pending", "requires_otp", "processing", "succeeded", "failed", "expired" ], "description": "Where the collection stands. succeeded , failed and expired are final." }, "amount": { "type": "integer", "description": "Amount requested from the customer, in minor units." }, "currency": { "type": "string", "description": "ISO 4217 currency code." }, "fee": { "type": [ "integer", "null" ], "description": "Monerail fee, set once the collection succeeds." }, "net": { "type": [ "integer", "null" ], "description": "Amount credited to your balance ( amount − fee ), set once the collection succeeds." }, "customer": { "type": "object", "description": "The paying customer.", "properties": { "name": { "type": "string", "description": "Customer name." }, "phone": { "type": "string", "description": "Mobile money number, international format without + ." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code." } } }, "operator": { "type": "string", "description": "Mobile money operator code, for example MTN or ORANGE ." }, "description": { "type": [ "string", "null" ], "description": "Your description." }, "client_reference": { "type": [ "string", "null" ], "description": "Your own reference, as sent at creation." }, "metadata": { "type": "object", "description": "Key-value pairs you attached at creation." }, "next_action": { "type": [ "object", "null" ], "description": "What the customer must do next, or null . type is customer_approval (approve on the phone; ussd_code is a fallback), otp (send the code with authorize ; when ussd_code is present, the customer dials it to get the code) or redirect (send the customer to url to approve).", "properties": { "type": { "type": "string", "enum": [ "customer_approval", "otp", "redirect" ], "description": "Kind of action." }, "message": { "type": [ "string", "null" ], "description": "Instruction from the operator, to show to your customer." }, "ussd_code": { "type": [ "string", "null" ], "description": "USSD code the customer dials: fallback for customer_approval , code generation for otp ." }, "url": { "type": [ "string", "null" ], "description": "redirect only: payment page to open for the customer." } } }, "failure_code": { "type": [ "string", "null" ], "enum": [ "failed", "expired", null ], "description": "failed or expired , when the collection did not succeed. The payment partner gives no finer reason for collections." }, "failure_message": { "type": [ "string", "null" ], "description": "Human-readable reason, when one is available." }, "created_at": { "type": "string", "description": "Creation time, ISO 8601 (UTC)." }, "updated_at": { "type": "string", "description": "Last change, ISO 8601 (UTC)." } }, "example": { "id": "3b8f6c1e-2a47-4d1b-9e35-7c0a9d2f4e61", "object": "collection", "livemode": false, "status": "pending", "amount": 5000, "currency": "XAF", "fee": null, "net": null, "customer": { "name": "Awa Ndiaye", "phone": "237670000999", "country": "CM" }, "operator": "MTN", "description": "Order 42", "client_reference": "order_42", "metadata": { "order_id": "42" }, "next_action": { "type": "customer_approval", "message": "A payment request was sent. The customer enters their PIN.", "ussd_code": "*126#" }, "failure_code": null, "failure_message": null, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:06.394Z" } }, "Payout": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier (UUID)." }, "livemode": { "type": "boolean", "description": "true for live objects, false for test objects." }, "object": { "type": "string", "description": "Always payout ." }, "status": { "type": "string", "enum": [ "pending", "processing", "succeeded", "failed" ], "description": "succeeded and failed are final. On failure, the amount and the fee return to your balance." }, "amount": { "type": "integer", "description": "Amount the recipient receives, in minor units." }, "currency": { "type": "string", "description": "ISO 4217 currency code." }, "fee": { "type": "integer", "description": "Monerail fee, debited from your balance on top of amount ." }, "recipient": { "type": "object", "description": "Who gets paid. Bank account numbers are masked.", "properties": { "type": { "type": "string", "enum": [ "mobile_money", "bank" ] }, "name": { "type": "string", "description": "Recipient name." }, "operator": { "type": "string", "description": "Mobile money only: operator code." }, "phone": { "type": "string", "description": "Mobile money only: number, international format." }, "bank_code": { "type": "string", "description": "Bank only: bank code from List banks ." }, "account": { "type": "string", "description": "Bank only: masked account number." }, "country": { "type": "string", "description": "Country code." } } }, "description": { "type": [ "string", "null" ], "description": "Your description." }, "client_reference": { "type": [ "string", "null" ], "description": "Your own reference, as sent at creation." }, "metadata": { "type": "object", "description": "Key-value pairs you attached at creation." }, "failure_code": { "type": [ "string", "null" ], "description": "Why it failed, when status is failed or expired ." }, "failure_message": { "type": [ "string", "null" ], "description": "Detail from the payment partner, when available." }, "created_at": { "type": "string", "description": "Creation time, ISO 8601 (UTC)." }, "updated_at": { "type": "string", "description": "Last change, ISO 8601 (UTC)." } }, "example": { "id": "7b05e2b6-6638-4088-a984-7155dfd6a036", "object": "payout", "livemode": false, "status": "pending", "amount": 150000, "currency": "XAF", "fee": 2250, "recipient": { "type": "mobile_money", "name": "Kossi Mensah", "operator": "MTN", "phone": "237670000777", "country": "CM" }, "description": "Invoice 2026-118", "client_reference": "inv_118", "metadata": {}, "failure_code": null, "failure_message": null, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:06.394Z" } }, "Settlement": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier (UUID)." }, "livemode": { "type": "boolean", "description": "true for live objects, false for test objects." }, "object": { "type": "string", "description": "Always settlement ." }, "status": { "type": "string", "enum": [ "pending", "processing", "succeeded", "failed" ], "description": "succeeded and failed are final." }, "amount": { "type": "integer", "description": "Amount sent to your settlement account, in minor units." }, "currency": { "type": "string", "description": "ISO 4217 currency code." }, "fee": { "type": "integer", "description": "Monerail fee." }, "recipient": { "type": "object", "description": "Your settlement account for this currency, as saved in the dashboard (same shape as on payouts: mobile_money or bank )." }, "description": { "type": [ "string", "null" ], "description": "Always null for settlements." }, "client_reference": { "type": [ "string", "null" ], "description": "Your own reference, as sent at creation." }, "metadata": { "type": "object", "description": "Key-value pairs you attached at creation." }, "failure_code": { "type": [ "string", "null" ], "description": "Why it failed, when status is failed or expired ." }, "failure_message": { "type": [ "string", "null" ], "description": "Detail from the payment partner, when available." }, "created_at": { "type": "string", "description": "Creation time, ISO 8601 (UTC)." }, "updated_at": { "type": "string", "description": "Last change, ISO 8601 (UTC)." } }, "example": { "id": "575f3a4b-ccd5-4949-9c4d-158127ccccd1", "object": "settlement", "livemode": false, "status": "pending", "amount": 2500000, "currency": "XAF", "fee": 0, "recipient": { "type": "bank", "name": "Acme SARL", "bank_code": "10005", "account": "••••0193", "country": "CM" }, "description": null, "client_reference": null, "metadata": {}, "failure_code": null, "failure_message": null, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:06.394Z" } }, "Transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier (UUID)." }, "livemode": { "type": "boolean", "description": "true for live objects, false for test objects." }, "object": { "type": "string", "description": "Always transaction ." }, "type": { "type": "string", "enum": [ "collection", "payout", "settlement", "payout_reversal", "settlement_reversal", "cards_balance_topup", "card_funding", "card_withdrawal", "card_payment", "card_refund", "card_reversal", "card_fee", "card_fee_refund", "card_issuing_fee", "card_funding_reversal", "conversion_debit", "conversion_credit", "conversion_reversal" ], "description": "What moved the money." }, "amount": { "type": "integer", "description": "Signed effect on your balance (or on the card, for card movements), in minor units. Negative means money out." }, "currency": { "type": [ "string", "null" ], "description": "Currency of the balance that moved. Card movements are in USD ." }, "gross": { "type": "integer", "description": "Gross amount of the underlying operation, before fees." }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed", "reversed" ], "description": "pending while a payout or settlement is on its way." }, "description": { "type": [ "string", "null" ], "description": "Short label." }, "counterparty": { "type": [ "string", "null" ], "description": "Customer, recipient or merchant name." }, "card": { "type": [ "string", "null" ], "description": "ID of the card, for card movements." }, "source": { "type": [ "object", "null" ], "description": "The collection, payout or settlement behind this transaction: { object, id } ." }, "created_at": { "type": "string", "description": "When the money moved, ISO 8601 (UTC)." } }, "example": { "id": "e664ee8d-8ae1-4b05-b76f-d2a1ddf74b50", "object": "transaction", "livemode": false, "type": "collection", "amount": 4875, "currency": "XAF", "gross": 5000, "status": "succeeded", "description": "Awa Ndiaye", "counterparty": "Awa Ndiaye", "card": null, "source": { "object": "collection", "id": "3b8f6c1e-2a47-4d1b-9e35-7c0a9d2f4e61" }, "created_at": "2026-10-30T13:47:09.807Z" } }, "Balance": { "type": "object", "properties": { "object": { "type": "string", "description": "Always balance ." }, "livemode": { "type": "boolean", "description": "true for live objects, false for test objects." }, "available": { "type": "array", "items": {}, "description": "One entry per currency: { currency, amount } , in minor units. This is what you can pay out or settle." }, "cards": { "type": [ "object", "null" ], "description": "Your cards balance, in US cents: { currency: \"USD\", amount } . New cards and card funding draw from it. null if the key’s creator does not have the Owner or Finance role." } }, "example": { "object": "balance", "livemode": false, "available": [ { "currency": "XAF", "amount": 3447189 }, { "currency": "KES", "amount": 7164025 } ], "cards": { "currency": "USD", "amount": 427555 } } }, "Cardholder": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier (UUID)." }, "livemode": { "type": "boolean", "description": "true for live objects, false for test objects." }, "object": { "type": "string", "description": "Always cardholder ." }, "type": { "type": "string", "enum": [ "team", "customer" ], "description": "team for your own staff, customer for your customers." }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": [ "string", "null" ], "description": "International format." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2." }, "city": { "type": [ "string", "null" ] }, "birth_date": { "type": [ "string", "null" ], "description": "YYYY-MM-DD ." }, "id_document": { "type": "string", "enum": [ "national_id", "passport", "driver_license", "voters_card" ], "description": "Identity document type." }, "id_number_last4": { "type": [ "string", "null" ], "description": "Last 4 characters of the document number. The full number is never returned." }, "verification": { "type": "object", "description": "Identity verification by the card issuer. A card can only be issued once status is verified .", "properties": { "status": { "type": "string", "enum": [ "pending", "in_review", "verified", "rejected" ] }, "reason": { "type": [ "string", "null" ], "description": "Why it was rejected." }, "verified_at": { "type": [ "string", "null" ], "description": "When it was verified." } } }, "created_at": { "type": "string", "description": "Creation time, ISO 8601 (UTC)." }, "updated_at": { "type": "string", "description": "Last change, ISO 8601 (UTC)." } }, "example": { "id": "5df6acd9-4bac-4e19-869c-fcde6b79f389", "object": "cardholder", "livemode": false, "type": "customer", "first_name": "Awa", "last_name": "Ndiaye", "email": "awa@example.com", "phone": "+237670000999", "country": "CM", "city": "Douala", "birth_date": "1991-02-03", "id_document": "national_id", "id_number_last4": "3408", "verification": { "status": "pending", "reason": null, "verified_at": null }, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:06.394Z" } }, "Card": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier (UUID)." }, "livemode": { "type": "boolean", "description": "true for live objects, false for test objects." }, "object": { "type": "string", "description": "Always card ." }, "type": { "type": "string", "enum": [ "team", "customer", "agent" ], "description": "agent cards belong to an AI agent and have no cardholder." }, "status": { "type": "string", "enum": [ "pending", "active", "frozen", "terminated", "failed" ], "description": "pending while the issuer creates the card, failed if it could not." }, "cardholder": { "type": [ "string", "null" ], "description": "Cardholder ID." }, "agent_name": { "type": [ "string", "null" ], "description": "Agent cards only." }, "label": { "type": [ "string", "null" ], "description": "Your label for the card." }, "network": { "type": "string", "enum": [ "visa", "mastercard" ] }, "last4": { "type": [ "string", "null" ], "description": "Last 4 digits of the card number." }, "exp_month": { "type": [ "integer", "null" ] }, "exp_year": { "type": [ "integer", "null" ] }, "currency": { "type": "string", "description": "Always USD ." }, "balance": { "type": [ "integer", "null" ], "description": "Card balance in US cents." }, "single_use": { "type": "boolean", "description": "Single-use card: it can be paid once; later payments are declined. It cannot be funded or withdrawn from." }, "spending_limit": { "type": [ "object", "null" ], "description": "{ amount, interval } with interval daily or per_transaction . Always null for single-use cards." }, "created_at": { "type": "string", "description": "Creation time, ISO 8601 (UTC)." }, "terminated_at": { "type": [ "string", "null" ] } }, "example": { "id": "ce2f0aea-7f87-4cbd-8383-03129d1253e0", "object": "card", "livemode": false, "type": "customer", "status": "active", "cardholder": "5df6acd9-4bac-4e19-869c-fcde6b79f389", "agent_name": null, "label": "Subscriptions", "network": "visa", "last4": "5904", "exp_month": 10, "exp_year": 2029, "currency": "USD", "balance": 950, "single_use": false, "spending_limit": { "amount": 20000, "interval": "daily" }, "created_at": "2026-10-30T13:47:06.394Z", "terminated_at": null } }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier (UUID)." }, "livemode": { "type": "boolean", "description": "true for live objects, false for test objects." }, "object": { "type": "string", "description": "Always webhook_endpoint ." }, "url": { "type": "string", "description": "HTTPS URL that receives the events." }, "events": { "type": "array", "items": {}, "description": "Subscribed event types. * means all, payout.* all payout events." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "secret": { "type": "string", "description": "Signing secret ( whsec_… ). Only in the original 201 response to the creation, never afterwards." }, "created_at": { "type": "string", "description": "Creation time, ISO 8601 (UTC)." } }, "example": { "id": "9a661b6d-2895-414e-b1d1-51e473582cbb", "object": "webhook_endpoint", "livemode": false, "url": "https://example.com/webhooks/monerail", "events": [ "collection.succeeded", "payout.*" ], "status": "enabled", "created_at": "2026-10-30T13:47:06.394Z" } }, "Event": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier (UUID)." }, "object": { "type": "string", "description": "Always event ." }, "type": { "type": "string", "description": "Event type, see the list ." }, "livemode": { "type": "boolean", "description": "true for live objects, false for test objects." }, "created_at": { "type": "string", "description": "When it happened, ISO 8601 (UTC)." }, "data": { "type": "object", "description": "data.object is the object concerned (collection, payout, card, transaction…), in its state when the event is read or delivered." } }, "example": { "id": "3ab70bfc-785d-45ce-99de-fd9ab67e5cd4", "object": "event", "type": "collection.succeeded", "livemode": false, "created_at": "2026-10-30T13:47:09.807Z", "data": { "object": { "id": "3b8f6c1e-2a47-4d1b-9e35-7c0a9d2f4e61", "object": "collection", "livemode": false, "status": "succeeded", "amount": 5000, "currency": "XAF", "fee": 125, "net": 4875, "customer": { "name": "Awa Ndiaye", "phone": "237670000999", "country": "CM" }, "operator": "MTN", "description": "Order 42", "client_reference": "order_42", "metadata": { "order_id": "42" }, "next_action": null, "failure_code": null, "failure_message": null, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:09.807Z" } } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "request_failed", "idempotency_error", "rate_limit_error", "api_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } } } } } } }, "tags": [ { "name": "Balance" }, { "name": "Collections" }, { "name": "Payouts" }, { "name": "Settlements" }, { "name": "Transactions" }, { "name": "Cardholders" }, { "name": "Cards" }, { "name": "Webhook endpoints" }, { "name": "Events" }, { "name": "Reference data" }, { "name": "Test helpers" } ], "paths": { "/v1/balance": { "get": { "operationId": "retrieveBalance", "summary": "Retrieve the balance", "tags": [ "Balance" ], "description": "Returns the balance of the mode of your key (test or live).", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "balance", "livemode": false, "available": [ { "currency": "XAF", "amount": 3447189 }, { "currency": "KES", "amount": 7164025 } ], "cards": { "currency": "USD", "amount": 427555 } }, "schema": { "$ref": "#/components/schemas/Balance" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/collections": { "post": { "operationId": "createCollection", "summary": "Create a collection", "tags": [ "Collections" ], "description": "Sends a payment request to the customer’s phone. Returns 201 with the collection, or 202 if the operator has not confirmed receipt yet (the collection is then processing ; its outcome arrives by webhook).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "integer", "description": "Amount in minor units of currency (whole francs for XAF, XOF and GNF; centimes for CDF, in multiples of 100). Integer only." }, "currency": { "type": "string", "enum": [ "XAF", "XOF", "GNF", "CDF", "KES", "GHS", "UGX", "TZS", "RWF" ], "description": "ISO 4217 code. Collections in NGN are not available and return 400 currency_unsupported ." }, "phone": { "type": "string", "description": "Customer mobile money number. International format ( 237670000000 or +237 670 00 00 00 ), or local format if country is known." }, "operator": { "type": "string", "description": "Operator code from List operators , for example MTN , ORANGE , WAVE , MPESA ." }, "customer": { "type": "object", "description": "The paying customer.", "properties": { "name": { "type": "string", "description": "Customer name, 2 to 80 characters." } }, "required": [ "name" ] }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 code. Required to collect in a country other than the main country of the currency: XAF defaults to CM (also GA, TD, CG, CF), XOF to SN (also CI, BJ, TG, BF, ML, NE), GNF to GN, CDF to CD. See Coverage ." }, "description": { "type": "string", "description": "Up to 500 characters." }, "client_reference": { "type": "string", "description": "Your own reference, up to 64 characters: letters, digits and _ . : / - ." }, "metadata": { "type": "object", "description": "Up to 20 key-value pairs. Keys up to 40 characters ( A-Z a-z 0-9 _ . - ), values are stored as strings up to 500 characters.", "additionalProperties": { "type": "string" } } }, "required": [ "amount", "currency", "phone", "operator", "customer" ] }, "example": { "amount": 5000, "currency": "XAF", "phone": "237670000999", "operator": "MTN", "customer": { "name": "Awa Ndiaye" }, "description": "Order 42", "client_reference": "order_42", "metadata": { "order_id": "42" } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "id": "3b8f6c1e-2a47-4d1b-9e35-7c0a9d2f4e61", "object": "collection", "livemode": false, "status": "pending", "amount": 5000, "currency": "XAF", "fee": null, "net": null, "customer": { "name": "Awa Ndiaye", "phone": "237670000999", "country": "CM" }, "operator": "MTN", "description": "Order 42", "client_reference": "order_42", "metadata": { "order_id": "42" }, "next_action": { "type": "customer_approval", "message": "A payment request was sent. The customer enters their PIN.", "ussd_code": "*126#" }, "failure_code": null, "failure_message": null, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:06.394Z" }, "schema": { "$ref": "#/components/schemas/Collection" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Accepted: the outcome is not final yet and arrives by webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } } } }, "get": { "operationId": "listCollections", "summary": "List collections", "tags": [ "Collections" ], "description": "Newest first.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Number of objects to return, 1 to 100." } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string", "description": "Cursor: the ID of the last object of the previous page." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "url": "/v1/collections", "data": [ { "id": "3b8f6c1e-2a47-4d1b-9e35-7c0a9d2f4e61", "object": "collection", "livemode": false, "status": "succeeded", "amount": 5000, "currency": "XAF", "fee": 125, "net": 4875, "customer": { "name": "Awa Ndiaye", "phone": "237670000999", "country": "CM" }, "operator": "MTN", "description": "Order 42", "client_reference": "order_42", "metadata": { "order_id": "42" }, "next_action": null, "failure_code": null, "failure_message": null, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:09.807Z" } ], "has_more": false }, "schema": { "type": "object", "properties": { "object": { "const": "list" }, "url": { "type": "string" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } } } } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/collections/{id}": { "get": { "operationId": "retrieveCollection", "summary": "Retrieve a collection", "tags": [ "Collections" ], "description": "Returns the collection. If it is still waiting, Monerail first asks the payment partner for news, so this call can also be used for polling (every few seconds at most).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "3b8f6c1e-2a47-4d1b-9e35-7c0a9d2f4e61", "object": "collection", "livemode": false, "status": "succeeded", "amount": 5000, "currency": "XAF", "fee": 125, "net": 4875, "customer": { "name": "Awa Ndiaye", "phone": "237670000999", "country": "CM" }, "operator": "MTN", "description": "Order 42", "client_reference": "order_42", "metadata": { "order_id": "42" }, "next_action": null, "failure_code": null, "failure_message": null, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:09.807Z" }, "schema": { "$ref": "#/components/schemas/Collection" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/collections/{id}/authorize": { "post": { "operationId": "authorize", "summary": "Authorize with a code", "tags": [ "Collections" ], "description": "For collections in requires_otp : sends the one-time code the customer received by SMS, or generated by dialing next_action.ussd_code . The collection moves to processing , then to its final status. In countries where the customer generates the code, 3 attempts are allowed.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "otp": { "type": "string", "description": "The code, 4 to 8 digits." } }, "required": [ "otp" ] }, "example": { "otp": "123456" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "9e2d4a7b-61c3-4f08-8b5e-2d7f1a3c9b40", "object": "collection", "livemode": false, "status": "processing", "amount": 2000, "currency": "XAF", "fee": null, "net": null, "customer": { "name": "Awa Ndiaye", "phone": "237690000002", "country": "CM" }, "operator": "ORANGE", "description": "Order 42", "client_reference": "order_42", "metadata": { "order_id": "42" }, "next_action": null, "failure_code": null, "failure_message": null, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:09.807Z" }, "schema": { "$ref": "#/components/schemas/Collection" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/collections/{id}/resend_otp": { "post": { "operationId": "resendOtp", "summary": "Resend the code", "tags": [ "Collections" ], "description": "Asks the operator to send a new code to the customer. Where the customer generates the code with a USSD code, nothing is sent: show next_action.ussd_code again.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "9e2d4a7b-61c3-4f08-8b5e-2d7f1a3c9b40", "object": "collection", "livemode": false, "status": "requires_otp", "amount": 2000, "currency": "XAF", "fee": null, "net": null, "customer": { "name": "Awa Ndiaye", "phone": "237690000002", "country": "CM" }, "operator": "ORANGE", "description": "Order 42", "client_reference": "order_42", "metadata": { "order_id": "42" }, "next_action": { "type": "otp", "message": "The customer received a one-time code by SMS." }, "failure_code": null, "failure_message": null, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:06.394Z" }, "schema": { "$ref": "#/components/schemas/Collection" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/payouts": { "post": { "operationId": "createPayout", "summary": "Create a payout", "tags": [ "Payouts" ], "description": "Reserves amount + fee on your balance and sends the payout. Fails with 402 balance_insufficient if your balance does not cover both. Returns 201 , or 202 with status: \"processing\" if the payment partner has not confirmed receipt yet: do not create the payout again, its outcome arrives by webhook.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "integer", "description": "Amount in minor units of currency (whole francs for XAF, XOF and GNF; centimes for CDF, in multiples of 100). Integer only." }, "currency": { "type": "string", "enum": [ "XAF", "XOF", "GNF", "CDF", "NGN", "KES", "GHS", "UGX", "TZS", "RWF" ], "description": "ISO 4217 code." }, "recipient": { "type": "object", "description": "Who gets paid.", "properties": { "type": { "type": "string", "enum": [ "mobile_money", "bank" ] }, "name": { "type": "string", "description": "Recipient name, 2 to 80 characters." }, "phone": { "type": "string", "description": "Mobile money: recipient number." }, "operator": { "type": "string", "description": "Mobile money: operator code." }, "bank_code": { "type": "string", "description": "Bank: a code from List banks , exactly as returned. Names and partial codes are refused with 400 bank_account_invalid ." }, "account": { "type": "string", "description": "Bank: account number." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2. Defaults to the main country of the currency (CM for XAF, SN for XOF, GN for GNF, CD for CDF). Bank payouts are available in the countries listed with bank transfer in Coverage ." } }, "required": [ "type", "name" ] }, "description": { "type": "string", "description": "Up to 500 characters." }, "client_reference": { "type": "string", "description": "Your own reference, up to 64 characters: letters, digits and _ . : / - ." }, "metadata": { "type": "object", "description": "Up to 20 key-value pairs. Keys up to 40 characters ( A-Z a-z 0-9 _ . - ), values are stored as strings up to 500 characters.", "additionalProperties": { "type": "string" } } }, "required": [ "amount", "currency", "recipient" ] }, "example": { "amount": 150000, "currency": "XAF", "recipient": { "type": "mobile_money", "name": "Kossi Mensah", "phone": "237670000777", "operator": "MTN" }, "description": "Invoice 2026-118", "client_reference": "inv_118" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "id": "7b05e2b6-6638-4088-a984-7155dfd6a036", "object": "payout", "livemode": false, "status": "pending", "amount": 150000, "currency": "XAF", "fee": 2250, "recipient": { "type": "mobile_money", "name": "Kossi Mensah", "operator": "MTN", "phone": "237670000777", "country": "CM" }, "description": "Invoice 2026-118", "client_reference": "inv_118", "metadata": {}, "failure_code": null, "failure_message": null, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:06.394Z" }, "schema": { "$ref": "#/components/schemas/Payout" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Accepted: the outcome is not final yet and arrives by webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" } } } } } }, "get": { "operationId": "listPayouts", "summary": "List payouts", "tags": [ "Payouts" ], "description": "Newest first.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Number of objects to return, 1 to 100." } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string", "description": "Cursor: the ID of the last object of the previous page." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "url": "/v1/payouts", "data": [ { "id": "7b05e2b6-6638-4088-a984-7155dfd6a036", "object": "payout", "livemode": false, "status": "pending", "amount": 150000, "currency": "XAF", "fee": 2250, "recipient": { "type": "bank", "name": "Kossi Mensah", "bank_code": "10005", "account": "••••4821", "country": "CM" }, "description": "Invoice 2026-118", "client_reference": "inv_118", "metadata": {}, "failure_code": null, "failure_message": null, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:06.394Z" } ], "has_more": false }, "schema": { "type": "object", "properties": { "object": { "const": "list" }, "url": { "type": "string" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payout" } } } } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/payouts/{id}": { "get": { "operationId": "retrievePayout", "summary": "Retrieve a payout", "tags": [ "Payouts" ], "description": "If the payout is still on its way, Monerail first asks the payment partner for news.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "7b05e2b6-6638-4088-a984-7155dfd6a036", "object": "payout", "livemode": false, "status": "succeeded", "amount": 150000, "currency": "XAF", "fee": 2250, "recipient": { "type": "mobile_money", "name": "Kossi Mensah", "operator": "MTN", "phone": "237670000777", "country": "CM" }, "description": "Invoice 2026-118", "client_reference": "inv_118", "metadata": {}, "failure_code": null, "failure_message": null, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:09.807Z" }, "schema": { "$ref": "#/components/schemas/Payout" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/settlements": { "post": { "operationId": "createSettlement", "summary": "Create a settlement", "tags": [ "Settlements" ], "description": "The destination is always your saved settlement account: it cannot be changed through the API.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "integer", "description": "Amount in minor units of currency (whole francs for XAF, XOF and GNF; centimes for CDF, in multiples of 100). Integer only." }, "currency": { "type": "string", "enum": [ "XAF", "XOF", "GNF", "CDF", "NGN", "KES", "GHS", "UGX", "TZS", "RWF" ], "description": "ISO 4217 code." } }, "required": [ "amount", "currency" ] }, "example": { "amount": 2500000, "currency": "XAF" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "id": "575f3a4b-ccd5-4949-9c4d-158127ccccd1", "object": "settlement", "livemode": false, "status": "pending", "amount": 2500000, "currency": "XAF", "fee": 0, "recipient": { "type": "bank", "name": "Acme SARL", "bank_code": "10005", "account": "••••0193", "country": "CM" }, "description": null, "client_reference": null, "metadata": {}, "failure_code": null, "failure_message": null, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:06.394Z" }, "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Accepted: the outcome is not final yet and arrives by webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } } } }, "get": { "operationId": "listSettlements", "summary": "List settlements", "tags": [ "Settlements" ], "description": "Newest first.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Number of objects to return, 1 to 100." } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string", "description": "Cursor: the ID of the last object of the previous page." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "url": "/v1/settlements", "data": [ { "id": "575f3a4b-ccd5-4949-9c4d-158127ccccd1", "object": "settlement", "livemode": false, "status": "pending", "amount": 2500000, "currency": "XAF", "fee": 0, "recipient": { "type": "bank", "name": "Acme SARL", "bank_code": "10005", "account": "••••0193", "country": "CM" }, "description": null, "client_reference": null, "metadata": {}, "failure_code": null, "failure_message": null, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:06.394Z" } ], "has_more": false }, "schema": { "type": "object", "properties": { "object": { "const": "list" }, "url": { "type": "string" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Settlement" } } } } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/settlements/{id}": { "get": { "operationId": "retrieveSettlement", "summary": "Retrieve a settlement", "tags": [ "Settlements" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "575f3a4b-ccd5-4949-9c4d-158127ccccd1", "object": "settlement", "livemode": false, "status": "succeeded", "amount": 2500000, "currency": "XAF", "fee": 0, "recipient": { "type": "bank", "name": "Acme SARL", "bank_code": "10005", "account": "••••0193", "country": "CM" }, "description": null, "client_reference": null, "metadata": {}, "failure_code": null, "failure_message": null, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:06.394Z" }, "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/transactions": { "get": { "operationId": "listTransactions", "summary": "List transactions", "tags": [ "Transactions" ], "description": "Newest first.", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "collection", "payout", "settlement", "payout_reversal", "settlement_reversal", "cards_balance_topup", "card_funding", "card_withdrawal", "card_payment", "card_refund", "card_reversal", "card_fee", "card_fee_refund", "card_issuing_fee", "card_funding_reversal", "conversion_debit", "conversion_credit", "conversion_reversal" ], "description": "Only return this type." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Number of objects to return, 1 to 100." } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string", "description": "Cursor: the ID of the last object of the previous page." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "url": "/v1/transactions", "data": [ { "id": "e664ee8d-8ae1-4b05-b76f-d2a1ddf74b50", "object": "transaction", "livemode": false, "type": "collection", "amount": 4875, "currency": "XAF", "gross": 5000, "status": "succeeded", "description": "Awa Ndiaye", "counterparty": "Awa Ndiaye", "card": null, "source": { "object": "collection", "id": "3b8f6c1e-2a47-4d1b-9e35-7c0a9d2f4e61" }, "created_at": "2026-10-30T13:47:09.807Z" } ], "has_more": true }, "schema": { "type": "object", "properties": { "object": { "const": "list" }, "url": { "type": "string" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } } } } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/transactions/{id}": { "get": { "operationId": "retrieveTransaction", "summary": "Retrieve a transaction", "tags": [ "Transactions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "e664ee8d-8ae1-4b05-b76f-d2a1ddf74b50", "object": "transaction", "livemode": false, "type": "collection", "amount": 4875, "currency": "XAF", "gross": 5000, "status": "succeeded", "description": "Awa Ndiaye", "counterparty": "Awa Ndiaye", "card": null, "source": { "object": "collection", "id": "3b8f6c1e-2a47-4d1b-9e35-7c0a9d2f4e61" }, "created_at": "2026-10-30T13:47:09.807Z" }, "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/cardholders": { "post": { "operationId": "createCardholder", "summary": "Create a cardholder", "tags": [ "Cardholders" ], "description": "Creates the cardholder with verification.status pending . Then submit the identity verification.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "first_name": { "type": "string", "description": "Up to 60 characters." }, "last_name": { "type": "string", "description": "Up to 60 characters." }, "email": { "type": "string", "description": "Unique per business." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2." }, "type": { "type": "string", "enum": [ "team", "customer" ] }, "phone": { "type": "string", "description": "International format. Required before verification." }, "city": { "type": "string" }, "birth_date": { "type": "string", "description": "YYYY-MM-DD ." }, "id_document": { "type": "string", "enum": [ "national_id", "passport", "driver_license", "voters_card" ], "description": "Document used for verification." }, "id_number": { "type": "string", "description": "Document number. Only its last 4 characters are returned." }, "address": { "type": "object", "description": "Home address, kept with the cardholder: line1 , line2 , city , state , postal_code . The verification asks for it again." } }, "required": [ "first_name", "last_name", "email", "country" ] }, "example": { "type": "customer", "first_name": "Awa", "last_name": "Ndiaye", "email": "awa@example.com", "phone": "+237670000999", "country": "CM", "city": "Douala", "birth_date": "1991-02-03", "id_document": "national_id" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "id": "5df6acd9-4bac-4e19-869c-fcde6b79f389", "object": "cardholder", "livemode": false, "type": "customer", "first_name": "Awa", "last_name": "Ndiaye", "email": "awa@example.com", "phone": "+237670000999", "country": "CM", "city": "Douala", "birth_date": "1991-02-03", "id_document": "national_id", "id_number_last4": "3408", "verification": { "status": "pending", "reason": null, "verified_at": null }, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:06.394Z" }, "schema": { "$ref": "#/components/schemas/Cardholder" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listCardholders", "summary": "List cardholders", "tags": [ "Cardholders" ], "description": "Newest first.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Number of objects to return, 1 to 100." } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string", "description": "Cursor: the ID of the last object of the previous page." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "url": "/v1/cardholders", "data": [ { "id": "5df6acd9-4bac-4e19-869c-fcde6b79f389", "object": "cardholder", "livemode": false, "type": "customer", "first_name": "Awa", "last_name": "Ndiaye", "email": "awa@example.com", "phone": "+237670000999", "country": "CM", "city": "Douala", "birth_date": "1991-02-03", "id_document": "national_id", "id_number_last4": "3408", "verification": { "status": "pending", "reason": null, "verified_at": null }, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:06.394Z" } ], "has_more": false }, "schema": { "type": "object", "properties": { "object": { "const": "list" }, "url": { "type": "string" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Cardholder" } } } } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/cardholders/{id}/verification": { "post": { "operationId": "verifyCardholder", "summary": "Submit identity verification", "tags": [ "Cardholders" ], "description": "Sends the identity details and document images to the card issuer. Returns 202 with verification.status in_review . The decision arrives with the cardholder.kyc_updated event. After a rejection, call it again with corrected details. If the cardholder is already verified, returns 200 with no change; while a review is in progress, documents are not sent again. The first name, last name and birth date must match the document exactly. Verification is per business: a person already verified by another business is verified again for yours. Limited to 5 calls per cardholder per 24 hours.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "id_number": { "type": "string", "description": "Document number." }, "birth_date": { "type": "string", "description": "YYYY-MM-DD ." }, "address": { "type": "object", "description": "Home address.", "properties": { "line1": { "type": "string" }, "city": { "type": "string" }, "line2": { "type": "string" }, "state": { "type": "string", "description": "Region. Defaults to the city." }, "postal_code": { "type": "string", "description": "Optional." } }, "required": [ "line1", "city" ] }, "documents": { "type": "object", "description": "Photos of the document, as base64 or data:image/…;base64, URIs. JPEG or PNG, 4 MB each at most. Sharp, uncropped, without glare, with the whole document visible.", "properties": { "front": { "type": "string", "description": "Front side." }, "back": { "type": "string", "description": "Back side. Required, except for a passport (front only)." } }, "required": [ "front" ] }, "place_of_birth": { "type": "string", "description": "City of birth, up to 80 characters." }, "phone": { "type": "string", "description": "International format, if not set on the cardholder." } }, "required": [ "id_number", "birth_date", "address", "documents", "place_of_birth" ] }, "example": { "id_number": "CM12345678", "birth_date": "1991-02-03", "place_of_birth": "Douala", "address": { "line1": "12 rue Joss", "city": "Douala", "state": "Littoral" }, "documents": { "front": "data:image/jpeg;base64,/9j/4AAQ…", "back": "data:image/jpeg;base64,/9j/4AAQ…" } } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "example": { "id": "5df6acd9-4bac-4e19-869c-fcde6b79f389", "object": "cardholder", "livemode": false, "type": "customer", "first_name": "Awa", "last_name": "Ndiaye", "email": "awa@example.com", "phone": "+237670000999", "country": "CM", "city": "Douala", "birth_date": "1991-02-03", "id_document": "national_id", "id_number_last4": "3408", "verification": { "status": "in_review", "reason": null, "verified_at": null }, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:09.807Z" }, "schema": { "$ref": "#/components/schemas/Cardholder" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/cardholders/{id}": { "get": { "operationId": "retrieveCardholder", "summary": "Retrieve a cardholder", "tags": [ "Cardholders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "5df6acd9-4bac-4e19-869c-fcde6b79f389", "object": "cardholder", "livemode": false, "type": "customer", "first_name": "Awa", "last_name": "Ndiaye", "email": "awa@example.com", "phone": "+237670000999", "country": "CM", "city": "Douala", "birth_date": "1991-02-03", "id_document": "national_id", "id_number_last4": "3408", "verification": { "status": "verified", "reason": null, "verified_at": "2026-10-30T13:47:09.807Z" }, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:06.394Z" }, "schema": { "$ref": "#/components/schemas/Cardholder" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/cards": { "post": { "operationId": "createCard", "summary": "Create a card", "tags": [ "Cards" ], "description": "Issues a card to a verified cardholder (or to an AI agent with type: \"agent\" ). amount is taken from your cards balance: it must cover the issuing fee plus at least $1. Returns 201 when the card is active, or 202 with status: \"pending\" while the issuer finishes or when its answer is not final yet; card.issued or card.issue_failed follows. The money returns to the cards balance only once a failure is final.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "integer", "description": "Initial funding in US cents, taken from the cards balance. Up to 10,000,000." }, "cardholder": { "type": "string", "description": "Cardholder ID. Required unless type is agent ." }, "type": { "type": "string", "enum": [ "team", "customer", "agent" ], "description": "agent for an agent card. For other cards, the card takes the type of its cardholder." }, "agent_name": { "type": "string", "description": "Required for agent cards. Up to 60 characters." }, "label": { "type": "string", "description": "Your label, up to 60 characters." }, "network": { "type": "string", "enum": [ "visa", "mastercard" ] }, "single_use": { "type": "boolean", "description": "The card can be paid once. Later payments are declined and nothing is charged. It cannot be funded or withdrawn from; its remaining balance returns to the cards balance when it is terminated (automatically 30 days after issue, or with terminate)." }, "spending_limit": { "type": "object", "description": "Spending limit. Not allowed with single_use: true (the card amount is the limit): sending both returns 400 parameter_invalid .", "properties": { "amount": { "type": "integer", "description": "In US cents." }, "interval": { "type": "string", "enum": [ "daily", "per_transaction" ] } }, "required": [ "amount", "interval" ] } }, "required": [ "amount" ] }, "example": { "cardholder": "5df6acd9-4bac-4e19-869c-fcde6b79f389", "type": "customer", "label": "Subscriptions", "amount": 1000, "spending_limit": { "amount": 20000, "interval": "daily" } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "id": "ce2f0aea-7f87-4cbd-8383-03129d1253e0", "object": "card", "livemode": false, "type": "customer", "status": "active", "cardholder": "5df6acd9-4bac-4e19-869c-fcde6b79f389", "agent_name": null, "label": "Subscriptions", "network": "visa", "last4": "5904", "exp_month": 10, "exp_year": 2029, "currency": "USD", "balance": 950, "single_use": false, "spending_limit": { "amount": 20000, "interval": "daily" }, "created_at": "2026-10-30T13:47:06.394Z", "terminated_at": null }, "schema": { "$ref": "#/components/schemas/Card" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Accepted: the outcome is not final yet and arrives by webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } } } }, "get": { "operationId": "listCards", "summary": "List cards", "tags": [ "Cards" ], "description": "Newest first.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "active", "frozen", "terminated", "failed" ], "description": "Only the cards with this status." } }, { "name": "cardholder", "in": "query", "required": false, "schema": { "type": "string", "description": "Only the cards of this cardholder (ID)." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Number of objects to return, 1 to 100." } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string", "description": "Cursor: the ID of the last object of the previous page." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "url": "/v1/cards", "data": [ { "id": "ce2f0aea-7f87-4cbd-8383-03129d1253e0", "object": "card", "livemode": false, "type": "customer", "status": "active", "cardholder": "5df6acd9-4bac-4e19-869c-fcde6b79f389", "agent_name": null, "label": "Subscriptions", "network": "visa", "last4": "5904", "exp_month": 10, "exp_year": 2029, "currency": "USD", "balance": 950, "single_use": false, "spending_limit": { "amount": 20000, "interval": "daily" }, "created_at": "2026-10-30T13:47:06.394Z", "terminated_at": null } ], "has_more": false }, "schema": { "type": "object", "properties": { "object": { "const": "list" }, "url": { "type": "string" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Card" } } } } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/cards/{id}": { "get": { "operationId": "retrieveCard", "summary": "Retrieve a card", "tags": [ "Cards" ], "description": "The full card number and CVC are never returned by the API. An Owner or Finance member can display them for 60 seconds in the dashboard (Show card details).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "ce2f0aea-7f87-4cbd-8383-03129d1253e0", "object": "card", "livemode": false, "type": "customer", "status": "active", "cardholder": "5df6acd9-4bac-4e19-869c-fcde6b79f389", "agent_name": null, "label": "Subscriptions", "network": "visa", "last4": "5904", "exp_month": 10, "exp_year": 2029, "currency": "USD", "balance": 950, "single_use": false, "spending_limit": { "amount": 20000, "interval": "daily" }, "created_at": "2026-10-30T13:47:06.394Z", "terminated_at": null }, "schema": { "$ref": "#/components/schemas/Card" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/cards/{id}/fund": { "post": { "operationId": "fundCard", "summary": "Fund a card", "tags": [ "Cards" ], "description": "Moves money from the cards balance to the card. Like every card action, returns 202 instead of 200 when the issuer’s answer is not final yet: the operation is not failed, and its result arrives by webhook ( card.funded ). Not available for single-use cards.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "integer", "description": "In US cents, up to 10,000,000." } }, "required": [ "amount" ] }, "example": { "amount": 5000 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "ce2f0aea-7f87-4cbd-8383-03129d1253e0", "object": "card", "livemode": false, "type": "customer", "status": "active", "cardholder": "5df6acd9-4bac-4e19-869c-fcde6b79f389", "agent_name": null, "label": "Subscriptions", "network": "visa", "last4": "5904", "exp_month": 10, "exp_year": 2029, "currency": "USD", "balance": 5950, "single_use": false, "spending_limit": { "amount": 20000, "interval": "daily" }, "created_at": "2026-10-30T13:47:06.394Z", "terminated_at": null }, "schema": { "$ref": "#/components/schemas/Card" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Accepted: the outcome is not final yet and arrives by webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } } } } }, "/v1/cards/{id}/withdraw": { "post": { "operationId": "withdrawCard", "summary": "Withdraw from a card", "tags": [ "Cards" ], "description": "Moves money from the card back to the cards balance. At least $1 must stay on the card. Not available for single-use cards. card.withdrawn confirms it.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "integer", "description": "In US cents." } }, "required": [ "amount" ] }, "example": { "amount": 500 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "ce2f0aea-7f87-4cbd-8383-03129d1253e0", "object": "card", "livemode": false, "type": "customer", "status": "active", "cardholder": "5df6acd9-4bac-4e19-869c-fcde6b79f389", "agent_name": null, "label": "Subscriptions", "network": "visa", "last4": "5904", "exp_month": 10, "exp_year": 2029, "currency": "USD", "balance": 450, "single_use": false, "spending_limit": { "amount": 20000, "interval": "daily" }, "created_at": "2026-10-30T13:47:06.394Z", "terminated_at": null }, "schema": { "$ref": "#/components/schemas/Card" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Accepted: the outcome is not final yet and arrives by webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } } } } }, "/v1/cards/{id}/freeze": { "post": { "operationId": "freezeCard", "summary": "Freeze a card", "tags": [ "Cards" ], "description": "Declines every new payment until the card is unfrozen. card.frozen confirms it.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "ce2f0aea-7f87-4cbd-8383-03129d1253e0", "object": "card", "livemode": false, "type": "customer", "status": "frozen", "cardholder": "5df6acd9-4bac-4e19-869c-fcde6b79f389", "agent_name": null, "label": "Subscriptions", "network": "visa", "last4": "5904", "exp_month": 10, "exp_year": 2029, "currency": "USD", "balance": 950, "single_use": false, "spending_limit": { "amount": 20000, "interval": "daily" }, "created_at": "2026-10-30T13:47:06.394Z", "terminated_at": null }, "schema": { "$ref": "#/components/schemas/Card" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Accepted: the outcome is not final yet and arrives by webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } } } } }, "/v1/cards/{id}/unfreeze": { "post": { "operationId": "unfreezeCard", "summary": "Unfreeze a card", "tags": [ "Cards" ], "description": "Accepts payments again. card.unfrozen confirms it.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "ce2f0aea-7f87-4cbd-8383-03129d1253e0", "object": "card", "livemode": false, "type": "customer", "status": "active", "cardholder": "5df6acd9-4bac-4e19-869c-fcde6b79f389", "agent_name": null, "label": "Subscriptions", "network": "visa", "last4": "5904", "exp_month": 10, "exp_year": 2029, "currency": "USD", "balance": 950, "single_use": false, "spending_limit": { "amount": 20000, "interval": "daily" }, "created_at": "2026-10-30T13:47:06.394Z", "terminated_at": null }, "schema": { "$ref": "#/components/schemas/Card" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Accepted: the outcome is not final yet and arrives by webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } } } } }, "/v1/cards/{id}/terminate": { "post": { "operationId": "terminateCard", "summary": "Terminate a card", "tags": [ "Cards" ], "description": "Closes the card for good. Its remaining balance returns to the cards balance. This cannot be undone. card.terminated confirms it.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "ce2f0aea-7f87-4cbd-8383-03129d1253e0", "object": "card", "livemode": false, "type": "customer", "status": "terminated", "cardholder": "5df6acd9-4bac-4e19-869c-fcde6b79f389", "agent_name": null, "label": "Subscriptions", "network": "visa", "last4": "5904", "exp_month": 10, "exp_year": 2029, "currency": "USD", "balance": 0, "single_use": false, "spending_limit": { "amount": 20000, "interval": "daily" }, "created_at": "2026-10-30T13:47:06.394Z", "terminated_at": "2026-10-30T13:47:09.807Z" }, "schema": { "$ref": "#/components/schemas/Card" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Accepted: the outcome is not final yet and arrives by webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } } } } }, "/v1/webhook_endpoints": { "post": { "operationId": "createWebhookEndpoint", "summary": "Create a webhook endpoint", "tags": [ "Webhook endpoints" ], "description": "The 201 response includes the signing secret . Store it: it is never returned again, not even when the request is replayed with the same Idempotency-Key . If you lose it, delete the endpoint and create a new one. Live endpoints need an approved business verification.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "description": "HTTPS URL, up to 500 characters, without user:password@ . The host must be a domain name: IP addresses are refused." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event types to receive: exact types, prefix.* or * ." } }, "required": [ "url", "events" ] }, "example": { "url": "https://example.com/webhooks/monerail", "events": [ "collection.succeeded", "payout.*" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "id": "9a661b6d-2895-414e-b1d1-51e473582cbb", "object": "webhook_endpoint", "livemode": false, "url": "https://example.com/webhooks/monerail", "events": [ "collection.succeeded", "payout.*" ], "status": "enabled", "created_at": "2026-10-30T13:47:06.394Z", "secret": "whsec_9b89c8bdc0b89f67637e017c49f9539d68b2132ea7492041" }, "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listWebhookEndpoints", "summary": "List webhook endpoints", "tags": [ "Webhook endpoints" ], "description": "Newest first. Test and live endpoints are listed separately, by the mode of the key.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Number of objects to return, 1 to 100." } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string", "description": "Cursor: the ID of the last object of the previous page." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "url": "/v1/webhook_endpoints", "data": [ { "id": "9a661b6d-2895-414e-b1d1-51e473582cbb", "object": "webhook_endpoint", "livemode": false, "url": "https://example.com/webhooks/monerail", "events": [ "collection.succeeded", "payout.*" ], "status": "enabled", "created_at": "2026-10-30T13:47:06.394Z" } ], "has_more": false }, "schema": { "type": "object", "properties": { "object": { "const": "list" }, "url": { "type": "string" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook_endpoints/{id}": { "get": { "operationId": "retrieveWebhookEndpoint", "summary": "Retrieve a webhook endpoint", "tags": [ "Webhook endpoints" ], "description": "The secret is not included.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "9a661b6d-2895-414e-b1d1-51e473582cbb", "object": "webhook_endpoint", "livemode": false, "url": "https://example.com/webhooks/monerail", "events": [ "collection.succeeded", "payout.*" ], "status": "enabled", "created_at": "2026-10-30T13:47:06.394Z" }, "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteWebhookEndpoint", "summary": "Delete a webhook endpoint", "tags": [ "Webhook endpoints" ], "description": "Stops all deliveries to this URL, including pending retries.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "9a661b6d-2895-414e-b1d1-51e473582cbb", "object": "webhook_endpoint", "deleted": true } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/events": { "get": { "operationId": "listEvents", "summary": "List events", "tags": [ "Events" ], "description": "Newest first.", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "Only this event type (exact type, no wildcard)." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Number of objects to return, 1 to 100." } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string", "description": "Cursor: the ID of the last object of the previous page." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "url": "/v1/events", "data": [ { "id": "3ab70bfc-785d-45ce-99de-fd9ab67e5cd4", "object": "event", "type": "collection.succeeded", "livemode": false, "created_at": "2026-10-30T13:47:09.807Z", "data": { "object": { "id": "3b8f6c1e-2a47-4d1b-9e35-7c0a9d2f4e61", "object": "collection", "livemode": false, "status": "succeeded", "amount": 5000, "currency": "XAF", "fee": 125, "net": 4875, "customer": { "name": "Awa Ndiaye", "phone": "237670000999", "country": "CM" }, "operator": "MTN", "description": "Order 42", "client_reference": "order_42", "metadata": { "order_id": "42" }, "next_action": null, "failure_code": null, "failure_message": null, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:09.807Z" } } } ], "has_more": true }, "schema": { "type": "object", "properties": { "object": { "const": "list" }, "url": { "type": "string" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/events/{id}": { "get": { "operationId": "retrieveEvent", "summary": "Retrieve an event", "tags": [ "Events" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "3ab70bfc-785d-45ce-99de-fd9ab67e5cd4", "object": "event", "type": "collection.succeeded", "livemode": false, "created_at": "2026-10-30T13:47:09.807Z", "data": { "object": { "id": "3b8f6c1e-2a47-4d1b-9e35-7c0a9d2f4e61", "object": "collection", "livemode": false, "status": "succeeded", "amount": 5000, "currency": "XAF", "fee": 125, "net": 4875, "customer": { "name": "Awa Ndiaye", "phone": "237670000999", "country": "CM" }, "operator": "MTN", "description": "Order 42", "client_reference": "order_42", "metadata": { "order_id": "42" }, "next_action": null, "failure_code": null, "failure_message": null, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:09.807Z" } } }, "schema": { "$ref": "#/components/schemas/Event" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/events/{id}/retry": { "post": { "operationId": "retryEvent", "summary": "Redeliver an event", "tags": [ "Events" ], "description": "Queues a new delivery of the event to every endpoint subscribed to it. redeliveries is the number of endpoints. This is the only way to redeliver an event: the dashboard has no redeliver button. Limited to 10 calls per event per hour.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "3ab70bfc-785d-45ce-99de-fd9ab67e5cd4", "object": "event", "redeliveries": 1 } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/operators": { "get": { "operationId": "listOperators", "summary": "List operators", "tags": [ "Reference data" ], "description": "Mobile money operators open for a currency, in every country of that currency, or in one country with country . authorization tells how customers approve: NONE , PIN (on the phone), OTP (code to send with authorize) or REDIRECT (payment page). Use code with the matching country when you create a collection or a payout.", "parameters": [ { "name": "currency", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "XAF", "XOF", "GNF", "CDF", "NGN", "KES", "GHS", "UGX", "TZS", "RWF" ] } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "description": "Optional ISO 3166-1 alpha-2 code, for example TD with XAF . Unknown pair: 400 country_unsupported ." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "url": "/v1/operators", "data": [ { "object": "operator", "code": "MTN", "name": "MTN Mobile Money", "country": "CM", "currency": "XAF", "authorization": [ "PIN" ], "ussd_code": "*126#" }, { "object": "operator", "code": "ORANGE", "name": "Orange Money", "country": "CM", "currency": "XAF", "authorization": [ "OTP" ], "ussd_code": "#150*50#" } ], "has_more": false } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/banks": { "get": { "operationId": "listBanks", "summary": "List banks", "tags": [ "Reference data" ], "description": "Banks you can pay out to in a country. Use code , unchanged, as recipient.bank_code .", "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "description": "ISO 3166-1 alpha-2." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "url": "/v1/banks", "data": [ { "object": "bank", "code": "10005", "name": "Afriland First Bank", "country": "CM" } ], "has_more": false } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/test/cardholders/{id}/verification": { "post": { "operationId": "testVerification", "summary": "Simulate a verification decision", "tags": [ "Test helpers" ], "description": "Approves or rejects a cardholder whose verification is in_review . The status changes within seconds and cardholder.kyc_updated is sent.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "result": { "type": "string", "enum": [ "approved", "rejected" ], "description": "The decision to simulate." }, "reason": { "type": "string", "description": "Only with rejected : becomes verification.reason . Up to 200 characters." } }, "required": [ "result" ] }, "example": { "result": "rejected", "reason": "Name/dob mismatch" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "example": { "id": "5df6acd9-4bac-4e19-869c-fcde6b79f389", "object": "cardholder", "livemode": false, "type": "customer", "first_name": "Awa", "last_name": "Ndiaye", "email": "awa@example.com", "phone": "+237670000999", "country": "CM", "city": "Douala", "birth_date": "1991-02-03", "id_document": "national_id", "id_number_last4": "3408", "verification": { "status": "in_review", "reason": null, "verified_at": null }, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:09.807Z" }, "schema": { "$ref": "#/components/schemas/Cardholder" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-test-mode-only": true } }, "/v1/test/cards/{id}/authorizations": { "post": { "operationId": "testAuthorization", "summary": "Simulate a card payment", "tags": [ "Test helpers" ], "description": "Simulates a merchant charging the card. An approved payment and its fee appear on the card within seconds, with a card.transaction event. A declined one sends card.authorization_declined , charges nothing and returns authorization: null .", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "integer", "description": "In US cents, up to 10,000,000." }, "merchant": { "type": "string", "description": "Merchant name, up to 40 characters." }, "status": { "type": "string", "enum": [ "approved", "declined" ], "description": "Outcome of the simulated payment." } }, "required": [ "amount" ] }, "example": { "amount": 400, "merchant": "Notion" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "example": { "object": "test_authorization", "card": "ce2f0aea-7f87-4cbd-8383-03129d1253e0", "amount": 400, "currency": "USD", "merchant": "Notion", "status": "approved", "authorization": "auth_7731" } } } }, "429": { "description": "Rate limit reached", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-test-mode-only": true } } } }