{ "openapi": "3.1.0", "info": { "title": "Monerails API", "version": "2026-10-30", "description": "Collections and payouts with mobile money across Africa, and virtual Visa and Mastercard cards. Docs: https://docs.monerails.com", "contact": { "email": "support@monerails.com" } }, "servers": [ { "url": "https://api.monerails.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": "Monerails 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": "237660000001", "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": "Monerails 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." } } }, "beneficiary": { "type": [ "string", "null" ], "description": "ID of the saved beneficiary paid, when the payout was created with beneficiary ." }, "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": "237660000001", "country": "CM" }, "beneficiary": null, "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" } }, "Beneficiary": { "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 beneficiary ." }, "type": { "type": "string", "enum": [ "mobile_money", "bank" ], "description": "Mobile money wallet or bank account." }, "name": { "type": "string", "description": "Beneficiary name, used as the recipient name of payouts." }, "nickname": { "type": [ "string", "null" ], "description": "Your own label, up to 40 characters." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code." }, "currency": { "type": "string", "description": "Currency of payouts to this beneficiary (the currency of the country)." }, "operator": { "type": [ "string", "null" ], "description": "Mobile money only: operator code." }, "phone": { "type": [ "string", "null" ], "description": "Mobile money only: number in E.164 format." }, "bank_code": { "type": [ "string", "null" ], "description": "Bank only: bank code from List banks ." }, "bank_name": { "type": [ "string", "null" ], "description": "Bank only: bank name." }, "account": { "type": [ "string", "null" ], "description": "Bank only: masked account number." }, "last_used_at": { "type": [ "string", "null" ], "description": "Time of the last payout created with this beneficiary." }, "created_at": { "type": "string", "description": "Creation time, ISO 8601 (UTC)." }, "updated_at": { "type": "string", "description": "Last change, ISO 8601 (UTC)." } }, "example": { "id": "4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34", "object": "beneficiary", "livemode": false, "type": "mobile_money", "name": "Kossi Mensah", "nickname": "Akwa supplier", "country": "CM", "currency": "XAF", "operator": "MTN", "phone": "+237660000001", "bank_code": null, "bank_name": null, "account": null, "last_used_at": 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": "Monerails 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": 37500, "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." }, "fee": { "type": [ "object", "null" ], "description": "For card_fee and card_fee_refund transactions: { type, payment, pass_through } . type is one of issuance , withdrawal , maintenance , processing (Monerails’ processing fee on a successful payment), issuer_cross_border (card issuer fee on a cross-border payment), decline , chargeback , network_fine . payment is the ID of the card_payment transaction the fee belongs to, or null . pass_through is true for third-party fees passed through at cost. null for other transactions." }, "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." }, "documents_on_file": { "type": "boolean", "description": "true when the document photos sent on creation are on file: the verification can be submitted without sending them again." } } }, "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, "documents_on_file": true }, "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": "237660000001", "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": "Beneficiaries" }, { "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, "description": "Optional for the API; send it on every POST that moves money. A retry with the same key and body within 24 hours replays the first response. See https://docs.monerails.com/idempotency/", "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": "237660000001", "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": "237660000001", "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." } }, { "name": "client_reference", "in": "query", "required": false, "schema": { "type": "string", "description": "Returns only the operations created with this client_reference . Use it to find an operation whose response was lost (see Idempotency )." } } ], "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": "237660000001", "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, Monerails 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": "237660000001", "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, "description": "Optional for the API; send it on every POST that moves money. A retry with the same key and body within 24 hours replays the first response. See https://docs.monerails.com/idempotency/", "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, "description": "Optional for the API; send it on every POST that moves money. A retry with the same key and body within 24 hours replays the first response. See https://docs.monerails.com/idempotency/", "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, "description": "Optional for the API; send it on every POST that moves money. A retry with the same key and body within 24 hours replays the first response. See https://docs.monerails.com/idempotency/", "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 with recipient ; optional with beneficiary (the beneficiary currency is used and, if given, must match)." }, "beneficiary": { "type": "string", "description": "ID of a saved beneficiary of the same mode, instead of recipient . Its saved details are used." }, "recipient": { "type": "object", "description": "Who gets paid. Required unless beneficiary is given; not both.", "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" ] }, "example": { "amount": 150000, "currency": "XAF", "recipient": { "type": "mobile_money", "name": "Kossi Mensah", "phone": "237660000001", "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": "237660000001", "country": "CM" }, "beneficiary": null, "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." } }, { "name": "client_reference", "in": "query", "required": false, "schema": { "type": "string", "description": "Returns only the operations created with this client_reference . Use it to find an operation whose response was lost (see Idempotency )." } } ], "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" }, "beneficiary": null, "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, Monerails 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": "237660000001", "country": "CM" }, "beneficiary": null, "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/beneficiaries": { "post": { "operationId": "createBeneficiary", "summary": "Create a beneficiary", "tags": [ "Beneficiaries" ], "description": "Checks the details with the same rules as payouts (country open to payouts, operator of the country, international number, test numbers in test mode, exact bank code) and saves them. Nothing is sent to the recipient.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional for the API; send it on every POST that moves money. A retry with the same key and body within 24 hours replays the first response. See https://docs.monerails.com/idempotency/", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "mobile_money", "bank" ] }, "name": { "type": "string", "description": "Beneficiary name, 2 to 80 characters." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 code of a country open to payouts." }, "currency": { "type": "string", "description": "ISO 4217 code. Defaults to the currency of the country." }, "nickname": { "type": "string", "description": "Your own label, up to 40 characters." }, "phone": { "type": "string", "description": "Mobile money: number in international format ( +237670000777 )." }, "operator": { "type": "string", "description": "Mobile money: operator code from List operators ." }, "bank_code": { "type": "string", "description": "Bank: a code from List banks , exactly as returned." }, "account": { "type": "string", "description": "Bank: account number, 6 to 34 letters or digits." } }, "required": [ "type", "name", "country" ] }, "example": { "type": "mobile_money", "name": "Kossi Mensah", "nickname": "Akwa supplier", "country": "CM", "phone": "+237660000001", "operator": "MTN" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "id": "4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34", "object": "beneficiary", "livemode": false, "type": "mobile_money", "name": "Kossi Mensah", "nickname": "Akwa supplier", "country": "CM", "currency": "XAF", "operator": "MTN", "phone": "+237660000001", "bank_code": null, "bank_name": null, "account": null, "last_used_at": null, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:06.394Z" }, "schema": { "$ref": "#/components/schemas/Beneficiary" } } } }, "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": "listBeneficiaries", "summary": "List beneficiaries", "tags": [ "Beneficiaries" ], "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." } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "mobile_money", "bank" ], "description": "Only this type." } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "description": "Only this country (ISO 3166-1 alpha-2)." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "url": "/v1/beneficiaries", "data": [ { "id": "4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34", "object": "beneficiary", "livemode": false, "type": "mobile_money", "name": "Kossi Mensah", "nickname": "Akwa supplier", "country": "CM", "currency": "XAF", "operator": "MTN", "phone": "+237660000001", "bank_code": null, "bank_name": null, "account": null, "last_used_at": null, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:06.394Z" }, { "id": "4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34", "object": "beneficiary", "livemode": false, "type": "bank", "name": "Kossi Mensah", "nickname": null, "country": "CM", "currency": "XAF", "operator": null, "phone": null, "bank_code": "10005", "bank_name": "Example Bank", "account": "••••4821", "last_used_at": "2026-10-30T13:47:09.807Z", "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/Beneficiary" } } } } } } }, "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/beneficiaries/{id}": { "get": { "operationId": "retrieveBeneficiary", "summary": "Retrieve a beneficiary", "tags": [ "Beneficiaries" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34", "object": "beneficiary", "livemode": false, "type": "mobile_money", "name": "Kossi Mensah", "nickname": "Akwa supplier", "country": "CM", "currency": "XAF", "operator": "MTN", "phone": "+237660000001", "bank_code": null, "bank_name": null, "account": null, "last_used_at": null, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:06.394Z" }, "schema": { "$ref": "#/components/schemas/Beneficiary" } } } }, "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" } } } } } }, "post": { "operationId": "updateBeneficiary", "summary": "Update a beneficiary", "tags": [ "Beneficiaries" ], "description": "Changes the parameters you send; the others keep their value. type cannot change. Send nickname: null to remove the nickname. The same checks as at creation apply.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional for the API; send it on every POST that moves money. A retry with the same key and body within 24 hours replays the first response. See https://docs.monerails.com/idempotency/", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "2 to 80 characters." }, "nickname": { "type": "string", "description": "Up to 40 characters, or null ." }, "country": { "type": "string" }, "phone": { "type": "string" }, "operator": { "type": "string" }, "bank_code": { "type": "string" }, "account": { "type": "string" } }, "required": [] }, "example": { "nickname": "Douala courier" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34", "object": "beneficiary", "livemode": false, "type": "mobile_money", "name": "Kossi Mensah", "nickname": "Douala courier", "country": "CM", "currency": "XAF", "operator": "MTN", "phone": "+237660000001", "bank_code": null, "bank_name": null, "account": null, "last_used_at": null, "created_at": "2026-10-30T13:47:06.394Z", "updated_at": "2026-10-30T13:47:09.807Z" }, "schema": { "$ref": "#/components/schemas/Beneficiary" } } } }, "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": "deleteBeneficiary", "summary": "Delete a beneficiary", "tags": [ "Beneficiaries" ], "description": "Removes the beneficiary from the list. Payouts already created are not affected.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34", "object": "beneficiary", "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/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, "description": "Optional for the API; send it on every POST that moves money. A retry with the same key and body within 24 hours replays the first response. See https://docs.monerails.com/idempotency/", "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": 37500, "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": 37500, "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": 37500, "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 . A photo of the identity document is required ( documents ): it is checked before anything is created and reused by the identity verification. Then submit the identity verification.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional for the API; send it on every POST that moves money. A retry with the same key and body within 24 hours replays the first response. See https://docs.monerails.com/idempotency/", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "first_name": { "type": "string", "description": "Exactly as on the identity document. 1 to 50 characters: letters (accents allowed), spaces, apostrophes, periods and hyphens." }, "last_name": { "type": "string", "description": "Same rules as first_name ." }, "email": { "type": "string", "description": "Valid address, up to 200 characters. Unique per business." }, "country": { "type": "string", "description": "Country of residence, ISO 3166-1 alpha-2, among: CM, GA, TD, CG, CF, CD, CI, SN, BJ, TG, BF, ML, NE, GN, NG, GH, KE, UG, TZ, RW, ZM, ZA. Otherwise country_unsupported ." }, "type": { "type": "string", "enum": [ "team", "customer" ] }, "phone": { "type": "string", "description": "Mobile number in international E.164 format ( +237670000999 ). A national number gets the country code of country . The national part must have the length used in that country, otherwise phone_invalid . Returned normalized." }, "birth_date": { "type": "string", "description": "YYYY-MM-DD , a real date, exactly as on the document. The cardholder must be at least 18 ( cardholder_underage )." }, "id_document": { "type": "string", "enum": [ "national_id", "passport", "driver_license", "voters_card" ], "description": "Document used for verification. In Ghana, national_id is the Ghana Card. A passport needs its photo page only; the other documents need both sides." }, "id_number": { "type": "string", "description": "Document number, as printed (upper-cased). Passport: 6 to 9 letters or digits, no spaces. Other documents: 4 to 30 characters among letters, digits, spaces, / and - . Optional here, required by the verification. Only its last 4 characters are returned." }, "city": { "type": "string", "description": "Optional. 2 to 60 characters, no digits." }, "address": { "type": "object", "description": "Home address, kept with the cardholder: line1 , line2 , city , state , postal_code . The verification asks for it again." }, "documents": { "type": "object", "description": "Photos of the identity document, as base64 or data:image/…;base64, URIs. JPEG or PNG, 4 MB each at most, at least 600 × 400 px. Missing: parameter_missing ; unreadable, too large or too small: document_invalid . param names the side.", "properties": { "front": { "type": "string", "description": "Front side (photo page of a passport)." }, "back": { "type": "string", "description": "Back side. Required, except for a passport." } }, "required": [ "front" ] } }, "required": [ "first_name", "last_name", "email", "country", "phone", "birth_date", "documents" ] }, "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", "documents": { "front": "data:image/jpeg;base64,/9j/4AAQ…", "back": "data:image/jpeg;base64,/9j/4AAQ…" } } } } }, "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, "documents_on_file": true }, "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, "documents_on_file": true }, "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, "description": "Optional for the API; send it on every POST that moves money. A retry with the same key and body within 24 hours replays the first response. See https://docs.monerails.com/idempotency/", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "id_number": { "type": "string", "description": "Document number, same rules as on creation (passport: 6 to 9 letters or digits; other documents: 4 to 30 characters)." }, "birth_date": { "type": "string", "description": "YYYY-MM-DD , 18 or older. Defaults to the cardholder’s birth_date ." }, "place_of_birth": { "type": "string", "description": "City of birth, as on the document. 2 to 60 characters, no digits." }, "address": { "type": "object", "description": "Home address. Accents are accepted and sent without them.", "properties": { "line1": { "type": "string", "description": "3 to 100 characters: letters, digits, spaces and , . - only." }, "line2": { "type": "string", "description": "Optional. Same characters as line1 , up to 100." }, "city": { "type": "string", "description": "2 to 60 characters, no digits." }, "state": { "type": "string", "description": "Region, province or state. 2 to 60 characters, no digits." }, "postal_code": { "type": "string", "description": "Optional. 1 to 10 letters, digits, spaces or hyphens. Leave it out where there is none." } }, "required": [ "line1", "city", "state" ] }, "documents": { "type": "object", "description": "Photos of the document, as base64 or data:image/…;base64, URIs. JPEG or PNG, 4 MB each at most, at least 600 × 400 px ( document_invalid otherwise). Sharp, uncropped, without glare, with the whole document visible. Optional when the photos were sent on creation ( verification.documents_on_file ); if sent, they replace them.", "properties": { "front": { "type": "string", "description": "Front side (photo page of a passport)." }, "back": { "type": "string", "description": "Back side. Required, except for a passport." } }, "required": [ "front" ] }, "phone": { "type": "string", "description": "Only if the cardholder has none. Same rules as on creation." } }, "required": [ "id_number", "place_of_birth", "address" ] }, "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, "documents_on_file": true }, "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, "description": "Optional for the API; send it on every POST that moves money. A retry with the same key and body within 24 hours replays the first response. See https://docs.monerails.com/idempotency/", "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, "description": "Optional for the API; send it on every POST that moves money. A retry with the same key and body within 24 hours replays the first response. See https://docs.monerails.com/idempotency/", "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, "description": "Optional for the API; send it on every POST that moves money. A retry with the same key and body within 24 hours replays the first response. See https://docs.monerails.com/idempotency/", "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, "description": "Optional for the API; send it on every POST that moves money. A retry with the same key and body within 24 hours replays the first response. See https://docs.monerails.com/idempotency/", "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, "description": "Optional for the API; send it on every POST that moves money. A retry with the same key and body within 24 hours replays the first response. See https://docs.monerails.com/idempotency/", "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, "description": "Optional for the API; send it on every POST that moves money. A retry with the same key and body within 24 hours replays the first response. See https://docs.monerails.com/idempotency/", "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, roll it with Rotate the secret . Live endpoints need an approved business verification.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional for the API; send it on every POST that moves money. A retry with the same key and body within 24 hours replays the first response. See https://docs.monerails.com/idempotency/", "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/webhook_endpoints/{id}/rotate_secret": { "post": { "operationId": "rotateWebhookEndpointSecret", "summary": "Rotate the secret", "tags": [ "Webhook endpoints" ], "description": "Returns the endpoint with its new signing secret , shown only in this response. The old secret stays valid for overlap_minutes ; meanwhile every delivery carries two v1 signatures (new secret first). One rotation per minute at most. See Webhooks .", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional for the API; send it on every POST that moves money. A retry with the same key and body within 24 hours replays the first response. See https://docs.monerails.com/idempotency/", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "overlap_minutes": { "type": "integer", "description": "How long the old secret keeps signing deliveries, in minutes: 0 to 10080. Default 1440 (24 hours). 0 revokes it immediately." } }, "required": [] }, "example": { "overlap_minutes": 1440 } } } }, "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", "secret": "whsec_5c1d0e7a2b9f48d3a6e1c0b7f4d2a9e8c3b6f1a0d5e2c7b4", "previous_secret_expires_at": "2026-11-02T09:30:00.000Z" }, "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" } } } } } } }, "/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": "237660000001", "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": "237660000001", "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, "description": "Optional for the API; send it on every POST that moves money. A retry with the same key and body within 24 hours replays the first response. See https://docs.monerails.com/idempotency/", "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 MoMo", "country": "CM", "currency": "XAF", "authorization": [ "NONE" ], "ussd_code": "*126#" }, { "object": "operator", "code": "ORANGE", "name": "Orange Money", "country": "CM", "currency": "XAF", "authorization": [ "NONE" ], "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 . Bank payouts are offered in Ghana, Nigeria, Kenya, Uganda, Tanzania and Rwanda, currently being activated ( 400 country_unsupported until they open); elsewhere this call returns 400 bank_transfer_unsupported : pay out to a mobile money wallet.", "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": "044", "name": "Access Bank", "country": "NG" } ], "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, "description": "Optional for the API; send it on every POST that moves money. A retry with the same key and body within 24 hours replays the first response. See https://docs.monerails.com/idempotency/", "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, "documents_on_file": true }, "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, "description": "Optional for the API; send it on every POST that moves money. A retry with the same key and body within 24 hours replays the first response. See https://docs.monerails.com/idempotency/", "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": "sim_3f9a1c2e7b5d4c8a9e0f1a2b3c4d5e6f" } } } }, "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 } } } }