{
    "openapi": "3.1.0",
    "info": {
        "title": "SendCheap Business API",
        "version": "1.0.0",
        "description": "Bills, collections, transfers, crypto and KYC for Nigerian businesses.\n\nEvery request needs `Authorization: Bearer <API token>`. POST bodies are JSON (`Content-Type: application/json`). Every response uses the same envelope: `status` (`success` or `failed`), `message` and `data`.",
        "contact": {
            "name": "SendCheap Support",
            "email": "business@sendcheap.ng"
        }
    },
    "servers": [
        {
            "url": "https://api.sendcheap.us/apps/business",
            "description": "Production"
        }
    ],
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "tags": [
        {
            "name": "Bills",
            "description": "Airtime, data, electricity, cable TV and betting."
        },
        {
            "name": "Collections",
            "description": "Receive bank transfers into static or per-invoice account numbers."
        },
        {
            "name": "Transfers",
            "description": "Send money from your wallet to any Nigerian bank account."
        },
        {
            "name": "Crypto",
            "description": "Receive and send cryptocurrency."
        },
        {
            "name": "KYC",
            "description": "BVN lookup, name matching and selfie comparison."
        }
    ],
    "paths": {
        "/bills/get_data_plan": {
            "get": {
                "tags": [
                    "Bills"
                ],
                "summary": "List data plans",
                "operationId": "getDataPlans",
                "description": "Returns the data bundles available for a network, sorted by price.\n\n**Network IDs:** `1` MTN, `2` GLO, `3` 9mobile, `4` Airtel.\n\n`variation_id` is the position of the plan in this list, so it can change when plans change. Always fetch the list shortly before buying and send the `variation_id` from that fetch.",
                "parameters": [
                    {
                        "name": "network_id",
                        "in": "query",
                        "required": true,
                        "description": "Network: 1 MTN, 2 GLO, 3 9mobile, 4 Airtel.",
                        "schema": {
                            "type": "integer",
                            "enum": [
                                1,
                                2,
                                3,
                                4
                            ]
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Data plans",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "plans": {
                                        "summary": "MTN data plans",
                                        "value": {
                                            "status": "success",
                                            "message": "successful",
                                            "data": [
                                                {
                                                    "discription": "(₦300) - 1 Day - 1DAY",
                                                    "amount": "300",
                                                    "bundle_code": "MTN-1GB-1D",
                                                    "network_id": 1,
                                                    "plan_bundle": "1 Day",
                                                    "expiration": "1DAY",
                                                    "variation_id": "1"
                                                },
                                                {
                                                    "discription": "(₦1500) - 30 Days - 30DAYS",
                                                    "amount": "1500",
                                                    "bundle_code": "MTN-2GB-30D",
                                                    "network_id": 1,
                                                    "plan_bundle": "30 Days",
                                                    "expiration": "30DAYS",
                                                    "variation_id": "2"
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/bills/buy_data": {
            "post": {
                "tags": [
                    "Bills"
                ],
                "summary": "Buy data",
                "operationId": "buyData",
                "description": "Buys a data bundle for a phone number. The price comes from the plan, and your wallet is debited for it.\n\n- **`Your Data Purchase ... Was Successful`** (`data.tranx_status` may still show `1` in this response) means the bundle was delivered.\n- **`Data Purchase Queued...`** means the provider is still processing it. Poll **Verify bill** with your `tranx_id` until it settles.\n- **`Failed And Reversed`** means it failed and your wallet has been refunded.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "network_id",
                                    "phone",
                                    "variation_id",
                                    "tranx_id"
                                ],
                                "properties": {
                                    "network_id": {
                                        "type": "integer",
                                        "description": "Network: 1 MTN, 2 GLO, 3 9mobile, 4 Airtel.",
                                        "enum": [
                                            1,
                                            2,
                                            3,
                                            4
                                        ],
                                        "example": 1
                                    },
                                    "phone": {
                                        "type": "string",
                                        "description": "Recipient phone number, 11 digits.",
                                        "minLength": 11,
                                        "example": "08031234567"
                                    },
                                    "variation_id": {
                                        "type": "string",
                                        "description": "The plan `variation_id` from List data plans.",
                                        "example": "2"
                                    },
                                    "tranx_id": {
                                        "type": "string",
                                        "description": "Your unique reference for this request, at least 10 characters. A reference can only be used once; reusing it returns \"duplicate transaction detected\". Store it so you can verify the transaction later.",
                                        "minLength": 10,
                                        "example": "ACME-20261121-000184"
                                    }
                                }
                            },
                            "example": {
                                "network_id": 1,
                                "phone": "08031234567",
                                "variation_id": "2",
                                "tranx_id": "ACME-20261121-000184"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Delivered or queued",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "success": {
                                        "summary": "Delivered",
                                        "value": {
                                            "status": "success",
                                            "message": "Your Data Purchase To 08031234567 Was Successful... Thank You",
                                            "data": {
                                                "id": 81234,
                                                "tranx_status": 1,
                                                "order_id": "ACME-20261121-000184",
                                                "tranx_type": 3,
                                                "network": "MTN",
                                                "amount": "1500.00",
                                                "charge": "0.00",
                                                "phone": "08031234567",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"248,500.0000\"}",
                                                "created_at": "2026-11-21 10:15:02",
                                                "updated_at": "2026-11-21 10:15:02",
                                                "percent": "0",
                                                "channel": "APP",
                                                "app_meta_data": null
                                            }
                                        }
                                    },
                                    "queued": {
                                        "summary": "Still processing at the provider",
                                        "value": {
                                            "status": "success",
                                            "message": "Data Purchase Queued...",
                                            "data": {
                                                "id": 81234,
                                                "tranx_status": 1,
                                                "order_id": "ACME-20261121-000184",
                                                "tranx_type": 3,
                                                "network": "MTN",
                                                "amount": "1500.00",
                                                "charge": "0.00",
                                                "phone": "08031234567",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"249,000.0000\"}",
                                                "created_at": "2026-11-21 10:15:02",
                                                "updated_at": "2026-11-21 10:15:02",
                                                "percent": "0",
                                                "channel": "APP",
                                                "app_meta_data": null
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "417": {
                        "description": "Rejected",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "reversed": {
                                        "summary": "Failed and refunded",
                                        "value": {
                                            "status": "failed",
                                            "message": "Data Purchase Failed And Reversed",
                                            "data": {
                                                "id": 81234,
                                                "tranx_status": 1,
                                                "order_id": "ACME-20261121-000184",
                                                "tranx_type": 3,
                                                "network": "MTN",
                                                "amount": "1500.00",
                                                "charge": "0.00",
                                                "phone": "08031234567",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"249,000.0000\"}",
                                                "created_at": "2026-11-21 10:15:02",
                                                "updated_at": "2026-11-21 10:15:02",
                                                "percent": "0",
                                                "channel": "APP",
                                                "app_meta_data": null
                                            }
                                        }
                                    },
                                    "low_balance": {
                                        "summary": "Wallet balance too low",
                                        "value": {
                                            "status": "failed",
                                            "message": "something went wrong... please try again...",
                                            "data": null
                                        }
                                    },
                                    "duplicate": {
                                        "summary": "The tranx_id was already used",
                                        "value": {
                                            "status": "failed",
                                            "message": "duplicate transaction detected....",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Outcome unknown",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unknown": {
                                        "summary": "The provider did not confirm the result. Do not retry with a new tranx_id; verify this one.",
                                        "value": {
                                            "status": "failed",
                                            "message": "Data Purchase Failed... Please Contact Support For Reversal",
                                            "data": {
                                                "id": 81234,
                                                "tranx_status": 1,
                                                "order_id": "ACME-20261121-000184",
                                                "tranx_type": 3,
                                                "network": "MTN",
                                                "amount": "1500.00",
                                                "charge": "0.00",
                                                "phone": "08031234567",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"249,000.0000\"}",
                                                "created_at": "2026-11-21 10:15:02",
                                                "updated_at": "2026-11-21 10:15:02",
                                                "percent": "0",
                                                "channel": "APP",
                                                "app_meta_data": null
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/bills/buy_airtime": {
            "post": {
                "tags": [
                    "Bills"
                ],
                "summary": "Buy airtime",
                "operationId": "buyAirtime",
                "description": "Sends airtime to a phone number. Minimum amount is **₦100**.\n\nResponses follow the same pattern as Buy data: successful, queued (verify later), or failed and reversed.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "network_id",
                                    "phone",
                                    "amount",
                                    "tranx_id"
                                ],
                                "properties": {
                                    "network_id": {
                                        "type": "integer",
                                        "description": "Network: 1 MTN, 2 GLO, 3 9mobile, 4 Airtel.",
                                        "enum": [
                                            1,
                                            2,
                                            3,
                                            4
                                        ],
                                        "example": 1
                                    },
                                    "phone": {
                                        "type": "string",
                                        "description": "Recipient phone number, 11 digits.",
                                        "minLength": 11,
                                        "example": "08031234567"
                                    },
                                    "amount": {
                                        "type": "number",
                                        "description": "Amount in naira. Minimum 100.",
                                        "minimum": 100,
                                        "example": 1000
                                    },
                                    "tranx_id": {
                                        "type": "string",
                                        "description": "Your unique reference for this request, at least 10 characters. A reference can only be used once; reusing it returns \"duplicate transaction detected\". Store it so you can verify the transaction later.",
                                        "minLength": 10,
                                        "example": "ACME-20261121-000184"
                                    }
                                }
                            },
                            "example": {
                                "network_id": 1,
                                "phone": "08031234567",
                                "amount": 1000,
                                "tranx_id": "ACME-20261121-000185"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Delivered or queued",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "success": {
                                        "summary": "Delivered",
                                        "value": {
                                            "status": "success",
                                            "message": "Your Airtime Purchase To 08031234567 Was Successful... Thank You",
                                            "data": {
                                                "id": 81234,
                                                "tranx_status": 1,
                                                "order_id": "ACME-20261121-000184",
                                                "tranx_type": 2,
                                                "network": "MTN",
                                                "amount": "1000.00",
                                                "charge": "0.00",
                                                "phone": "08031234567",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"249,000.0000\"}",
                                                "created_at": "2026-11-21 10:15:02",
                                                "updated_at": "2026-11-21 10:15:02",
                                                "percent": "0",
                                                "channel": "APP",
                                                "app_meta_data": null
                                            }
                                        }
                                    },
                                    "queued": {
                                        "summary": "Still processing at the provider",
                                        "value": {
                                            "status": "success",
                                            "message": "Airtime Purchase Queued...",
                                            "data": []
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "417": {
                        "description": "Rejected",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "reversed": {
                                        "summary": "Failed and refunded",
                                        "value": {
                                            "status": "failed",
                                            "message": "Airtime Purchase Failed And Reversed",
                                            "data": {
                                                "id": 81234,
                                                "tranx_status": 1,
                                                "order_id": "ACME-20261121-000184",
                                                "tranx_type": 2,
                                                "network": "MTN",
                                                "amount": "1000.00",
                                                "charge": "0.00",
                                                "phone": "08031234567",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"249,000.0000\"}",
                                                "created_at": "2026-11-21 10:15:02",
                                                "updated_at": "2026-11-21 10:15:02",
                                                "percent": "0",
                                                "channel": "APP",
                                                "app_meta_data": null
                                            }
                                        }
                                    },
                                    "minimum": {
                                        "summary": "Below the minimum",
                                        "value": {
                                            "status": "failed",
                                            "message": "unable to perform purchase... Minimum purchase amount is (NGN100)",
                                            "data": null
                                        }
                                    },
                                    "duplicate": {
                                        "summary": "The tranx_id was already used",
                                        "value": {
                                            "status": "failed",
                                            "message": "duplicate transaction detected....",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/bills/get_electricity_provider": {
            "get": {
                "tags": [
                    "Bills"
                ],
                "summary": "List electricity providers",
                "operationId": "getElectricityProviders",
                "description": "Returns the electricity distribution companies (DisCos). Pass a provider's `id`, `name` or `m_id` as `disco_name` when resolving a meter or buying electricity.",
                "responses": {
                    "200": {
                        "description": "Providers",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "providers": {
                                        "summary": "DisCos",
                                        "value": {
                                            "status": "success",
                                            "message": "successful",
                                            "data": [
                                                {
                                                    "id": "61efac27da92348f9dde5f74",
                                                    "name": "Ikeja Electric",
                                                    "m_id": "IKEDC"
                                                },
                                                {
                                                    "id": "61efac35da92348f9dde5f77",
                                                    "name": "Eko Electricity",
                                                    "m_id": "EKEDC"
                                                },
                                                {
                                                    "id": "61efac51da92348f9dde5f7d",
                                                    "name": "Abuja Electricity",
                                                    "m_id": "AEDC"
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "417": {
                        "description": "Provider list unavailable",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unavailable": {
                                        "summary": "Temporary provider error",
                                        "value": {
                                            "status": "failed",
                                            "message": "unable to fetch electricity providers... please try again",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/bills/resolve_electricity": {
            "post": {
                "tags": [
                    "Bills"
                ],
                "summary": "Resolve meter",
                "operationId": "resolveMeter",
                "description": "Looks up a meter number and returns the customer name, address and meter type. Show this to your customer before buying.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "disco_name",
                                    "meter_no"
                                ],
                                "properties": {
                                    "disco_name": {
                                        "type": "string",
                                        "description": "Provider `id`, `name` or `m_id` from List electricity providers.",
                                        "example": "IKEDC"
                                    },
                                    "meter_no": {
                                        "type": "string",
                                        "description": "Meter number.",
                                        "example": "45031234567"
                                    }
                                }
                            },
                            "example": {
                                "disco_name": "IKEDC",
                                "meter_no": "45031234567"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Meter found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "found": {
                                        "summary": "Meter details",
                                        "value": {
                                            "status": "success",
                                            "message": "successful",
                                            "data": {
                                                "name": "ADEBAYO OLUWASEUN",
                                                "address": "12 Allen Avenue, Ikeja",
                                                "meter_type": "PREPAID",
                                                "disco_name": "IKEDC"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    },
                                    "not_found": {
                                        "summary": "Meter not found",
                                        "value": {
                                            "status": "failed",
                                            "message": "User not found",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/bills/buy_electricity": {
            "post": {
                "tags": [
                    "Bills"
                ],
                "summary": "Buy electricity",
                "operationId": "buyElectricity",
                "description": "Buys electricity units for a meter. Minimum amount is **₦200**. The meter is verified again before payment.\n\nFor **prepaid** meters the token is returned in `data.token` on success. If the purchase is queued, the token is delivered once **Verify bill** shows it as successful.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "disco_name",
                                    "meter_no",
                                    "amount",
                                    "phone",
                                    "name",
                                    "address",
                                    "tranx_id"
                                ],
                                "properties": {
                                    "disco_name": {
                                        "type": "string",
                                        "description": "Provider `id`, `name` or `m_id`.",
                                        "example": "IKEDC"
                                    },
                                    "meter_no": {
                                        "type": "string",
                                        "description": "Meter number.",
                                        "example": "45031234567"
                                    },
                                    "amount": {
                                        "type": "number",
                                        "description": "Amount in naira. Minimum 200.",
                                        "minimum": 200,
                                        "example": 5000
                                    },
                                    "phone": {
                                        "type": "string",
                                        "description": "Customer phone number, 11 digits.",
                                        "minLength": 11,
                                        "example": "08031234567"
                                    },
                                    "name": {
                                        "type": "string",
                                        "description": "Customer name (from Resolve meter).",
                                        "example": "ADEBAYO OLUWASEUN"
                                    },
                                    "address": {
                                        "type": "string",
                                        "description": "Customer address (from Resolve meter).",
                                        "example": "12 Allen Avenue, Ikeja"
                                    },
                                    "meter_type": {
                                        "type": "string",
                                        "description": "Optional. `PREPAID` or `POSTPAID`. Detected from the meter when omitted.",
                                        "example": "PREPAID"
                                    },
                                    "tranx_id": {
                                        "type": "string",
                                        "description": "Your unique reference for this request, at least 10 characters. A reference can only be used once; reusing it returns \"duplicate transaction detected\". Store it so you can verify the transaction later.",
                                        "minLength": 10,
                                        "example": "ACME-20261121-000184"
                                    }
                                }
                            },
                            "example": {
                                "disco_name": "IKEDC",
                                "meter_no": "45031234567",
                                "amount": 5000,
                                "phone": "08031234567",
                                "name": "ADEBAYO OLUWASEUN",
                                "address": "12 Allen Avenue, Ikeja",
                                "tranx_id": "ACME-20261121-000186"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Delivered or queued",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "success": {
                                        "summary": "Delivered with token",
                                        "value": {
                                            "status": "success",
                                            "message": "Your Electricity Purchase To 45031234567 Was Successful... Thank You",
                                            "data": {
                                                "id": 81234,
                                                "tranx_status": 1,
                                                "order_id": "ACME-20261121-000184",
                                                "tranx_type": 19,
                                                "network": "IKEDC",
                                                "amount": "5000.00",
                                                "charge": "0.00",
                                                "phone": "45031234567",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"245,000.0000\"}",
                                                "created_at": "2026-11-21 10:15:02",
                                                "updated_at": "2026-11-21 10:15:02",
                                                "percent": "0",
                                                "channel": "APP",
                                                "app_meta_data": null,
                                                "token": "1234-5678-9012-3456-7890"
                                            }
                                        }
                                    },
                                    "queued": {
                                        "summary": "Still processing at the provider",
                                        "value": {
                                            "status": "success",
                                            "message": "Electricity Purchase Queued...",
                                            "data": {
                                                "id": 81234,
                                                "tranx_status": 1,
                                                "order_id": "ACME-20261121-000184",
                                                "tranx_type": 19,
                                                "network": "IKEDC",
                                                "amount": "5000.00",
                                                "charge": "0.00",
                                                "phone": "45031234567",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"249,000.0000\"}",
                                                "created_at": "2026-11-21 10:15:02",
                                                "updated_at": "2026-11-21 10:15:02",
                                                "percent": "0",
                                                "channel": "APP",
                                                "app_meta_data": null
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "417": {
                        "description": "Rejected",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "reversed": {
                                        "summary": "Failed and refunded",
                                        "value": {
                                            "status": "failed",
                                            "message": "Electricity Purchase Failed And Reversed",
                                            "data": {
                                                "id": 81234,
                                                "tranx_status": 1,
                                                "order_id": "ACME-20261121-000184",
                                                "tranx_type": 19,
                                                "network": "IKEDC",
                                                "amount": "5000.00",
                                                "charge": "0.00",
                                                "phone": "45031234567",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"249,000.0000\"}",
                                                "created_at": "2026-11-21 10:15:02",
                                                "updated_at": "2026-11-21 10:15:02",
                                                "percent": "0",
                                                "channel": "APP",
                                                "app_meta_data": null
                                            }
                                        }
                                    },
                                    "bad_meter": {
                                        "summary": "Meter could not be verified",
                                        "value": {
                                            "status": "failed",
                                            "message": "unable to verify meter number... please check and try again",
                                            "data": null
                                        }
                                    },
                                    "bad_disco": {
                                        "summary": "Unknown provider",
                                        "value": {
                                            "status": "failed",
                                            "message": "electricity provider not found... use get_electricity_provider for the list of providers",
                                            "data": null
                                        }
                                    },
                                    "duplicate": {
                                        "summary": "The tranx_id was already used",
                                        "value": {
                                            "status": "failed",
                                            "message": "duplicate transaction detected....",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/bills/get_tv_plan": {
            "get": {
                "tags": [
                    "Bills"
                ],
                "summary": "List TV plans",
                "operationId": "getTvPlans",
                "description": "Returns the cable TV packages for a provider, sorted by price.\n\n**TV IDs:** `1` GOtv, `2` DStv, `3` StarTimes.\n\nSend the plan `code` to Buy cable TV. The price is fixed by the plan.",
                "parameters": [
                    {
                        "name": "tv_id",
                        "in": "query",
                        "required": true,
                        "description": "TV provider: 1 GOtv, 2 DStv, 3 StarTimes.",
                        "schema": {
                            "type": "integer",
                            "enum": [
                                1,
                                2,
                                3
                            ]
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "TV plans",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "plans": {
                                        "summary": "GOtv packages",
                                        "value": {
                                            "status": "success",
                                            "message": "successful",
                                            "data": [
                                                {
                                                    "id": "1472",
                                                    "code": "1472",
                                                    "name": "GOtv Smallie",
                                                    "description": "GOtv Smallie",
                                                    "discription": "GOtv Smallie",
                                                    "amount": "1900",
                                                    "price": "1900",
                                                    "duration": "",
                                                    "bundle_code": "1472",
                                                    "type": "gotv"
                                                },
                                                {
                                                    "id": "1475",
                                                    "code": "1475",
                                                    "name": "GOtv Supa Plus",
                                                    "description": "GOtv Supa Plus",
                                                    "discription": "GOtv Supa Plus",
                                                    "amount": "16800",
                                                    "price": "16800",
                                                    "duration": "",
                                                    "bundle_code": "1475",
                                                    "type": "gotv"
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/bills/resolve_cable": {
            "post": {
                "tags": [
                    "Bills"
                ],
                "summary": "Resolve smartcard",
                "operationId": "resolveSmartcard",
                "description": "Looks up a smartcard / IUC number and returns the account holder name.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "tv_id",
                                    "smart_card_no"
                                ],
                                "properties": {
                                    "tv_id": {
                                        "type": "integer",
                                        "description": "TV provider: 1 GOtv, 2 DStv, 3 StarTimes.",
                                        "enum": [
                                            1,
                                            2,
                                            3
                                        ],
                                        "example": 1
                                    },
                                    "smart_card_no": {
                                        "type": "string",
                                        "description": "Smartcard / IUC number.",
                                        "example": "7023456789"
                                    }
                                }
                            },
                            "example": {
                                "tv_id": 1,
                                "smart_card_no": "7023456789"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Smartcard found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "found": {
                                        "summary": "Account holder",
                                        "value": {
                                            "status": "success",
                                            "message": "successful",
                                            "data": {
                                                "name": "ADEBAYO OLUWASEUN",
                                                "customerName": "ADEBAYO OLUWASEUN",
                                                "customer_name": "ADEBAYO OLUWASEUN",
                                                "smartCardNo": "7023456789",
                                                "smart_card_no": "7023456789",
                                                "type": "gotv"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    },
                                    "not_found": {
                                        "summary": "Smartcard not found",
                                        "value": {
                                            "status": "failed",
                                            "message": "unable to validate smart card number...",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/bills/buy_cable": {
            "post": {
                "tags": [
                    "Bills"
                ],
                "summary": "Buy cable TV",
                "operationId": "buyCable",
                "description": "Pays for a cable TV package on a smartcard. The amount is the plan price from List TV plans.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "tv_id",
                                    "code",
                                    "smart_card_no",
                                    "tranx_id"
                                ],
                                "properties": {
                                    "tv_id": {
                                        "type": "integer",
                                        "description": "TV provider: 1 GOtv, 2 DStv, 3 StarTimes.",
                                        "enum": [
                                            1,
                                            2,
                                            3
                                        ],
                                        "example": 1
                                    },
                                    "code": {
                                        "type": "string",
                                        "description": "Plan `code` from List TV plans.",
                                        "example": "1472"
                                    },
                                    "smart_card_no": {
                                        "type": "string",
                                        "description": "Smartcard / IUC number, at least 8 characters.",
                                        "minLength": 8,
                                        "example": "7023456789"
                                    },
                                    "tranx_id": {
                                        "type": "string",
                                        "description": "Your unique reference for this request, at least 10 characters. A reference can only be used once; reusing it returns \"duplicate transaction detected\". Store it so you can verify the transaction later.",
                                        "minLength": 10,
                                        "example": "ACME-20261121-000184"
                                    }
                                }
                            },
                            "example": {
                                "tv_id": 1,
                                "code": "1472",
                                "smart_card_no": "7023456789",
                                "tranx_id": "ACME-20261121-000187"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Delivered or queued",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "success": {
                                        "summary": "Delivered",
                                        "value": {
                                            "status": "success",
                                            "message": "Your Cable Purchase To 7023456789 Was Successful... Thank You",
                                            "data": {
                                                "id": 81234,
                                                "tranx_status": 1,
                                                "order_id": "ACME-20261121-000184",
                                                "tranx_type": 23,
                                                "network": "GOtv Smallie",
                                                "amount": "1900.00",
                                                "charge": "0.00",
                                                "phone": "7023456789",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"248,100.0000\"}",
                                                "created_at": "2026-11-21 10:15:02",
                                                "updated_at": "2026-11-21 10:15:02",
                                                "percent": "0",
                                                "channel": "APP",
                                                "app_meta_data": null
                                            }
                                        }
                                    },
                                    "queued": {
                                        "summary": "Still processing at the provider",
                                        "value": {
                                            "status": "success",
                                            "message": "Cable Purchase Queued...",
                                            "data": {
                                                "id": 81234,
                                                "tranx_status": 1,
                                                "order_id": "ACME-20261121-000184",
                                                "tranx_type": 23,
                                                "network": "GOtv Smallie",
                                                "amount": "1900.00",
                                                "charge": "0.00",
                                                "phone": "7023456789",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"249,000.0000\"}",
                                                "created_at": "2026-11-21 10:15:02",
                                                "updated_at": "2026-11-21 10:15:02",
                                                "percent": "0",
                                                "channel": "APP",
                                                "app_meta_data": null
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "417": {
                        "description": "Rejected",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "reversed": {
                                        "summary": "Failed and refunded",
                                        "value": {
                                            "status": "failed",
                                            "message": "Cable Purchase Failed And Reversed",
                                            "data": {
                                                "id": 81234,
                                                "tranx_status": 1,
                                                "order_id": "ACME-20261121-000184",
                                                "tranx_type": 23,
                                                "network": "GOtv Smallie",
                                                "amount": "1900.00",
                                                "charge": "0.00",
                                                "phone": "7023456789",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"249,000.0000\"}",
                                                "created_at": "2026-11-21 10:15:02",
                                                "updated_at": "2026-11-21 10:15:02",
                                                "percent": "0",
                                                "channel": "APP",
                                                "app_meta_data": null
                                            }
                                        }
                                    },
                                    "bad_plan": {
                                        "summary": "Unknown plan code",
                                        "value": {
                                            "status": "failed",
                                            "message": "cable plan not found... please try again...",
                                            "data": null
                                        }
                                    },
                                    "duplicate": {
                                        "summary": "The tranx_id was already used",
                                        "value": {
                                            "status": "failed",
                                            "message": "duplicate transaction detected....",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Outcome unknown",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unknown": {
                                        "summary": "Not confirmed yet. Verify this tranx_id instead of retrying.",
                                        "value": {
                                            "status": "failed",
                                            "message": "Cable Purchase Failed... Please Contact Support",
                                            "data": {
                                                "id": 81234,
                                                "tranx_status": 1,
                                                "order_id": "ACME-20261121-000184",
                                                "tranx_type": 23,
                                                "network": "GOtv Smallie",
                                                "amount": "1900.00",
                                                "charge": "0.00",
                                                "phone": "7023456789",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"249,000.0000\"}",
                                                "created_at": "2026-11-21 10:15:02",
                                                "updated_at": "2026-11-21 10:15:02",
                                                "percent": "0",
                                                "channel": "APP",
                                                "app_meta_data": null
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/bills/get_betting_provider": {
            "get": {
                "tags": [
                    "Bills"
                ],
                "summary": "List betting providers",
                "operationId": "getBettingProviders",
                "description": "Returns the betting platforms you can fund. Use the provider identifier as `betting_provider` / `provider`.",
                "responses": {
                    "200": {
                        "description": "Providers",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "providers": {
                                        "summary": "Betting platforms",
                                        "value": {
                                            "status": "success",
                                            "message": "retrieved successfully",
                                            "data": [
                                                {
                                                    "name": "Bet9ja",
                                                    "type": "BET9JA"
                                                },
                                                {
                                                    "name": "SportyBet",
                                                    "type": "SPORTYBET"
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/bills/resolve_betting": {
            "post": {
                "tags": [
                    "Bills"
                ],
                "summary": "Resolve betting account",
                "operationId": "resolveBetting",
                "description": "Looks up a customer ID on a betting platform and returns the account name.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "betting_provider",
                                    "user"
                                ],
                                "properties": {
                                    "betting_provider": {
                                        "type": "string",
                                        "description": "Provider identifier from List betting providers.",
                                        "example": "BET9JA"
                                    },
                                    "user": {
                                        "type": "string",
                                        "description": "The customer ID on the betting platform.",
                                        "example": "1234567"
                                    }
                                }
                            },
                            "example": {
                                "betting_provider": "BET9JA",
                                "user": "1234567"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Account found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "found": {
                                        "summary": "Betting account",
                                        "value": {
                                            "status": "success",
                                            "message": "successful",
                                            "data": {
                                                "customerId": "1234567",
                                                "name": "ADEBAYO OLUWASEUN",
                                                "type": "BET9JA"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    },
                                    "not_found": {
                                        "summary": "Account not found",
                                        "value": {
                                            "status": "failed",
                                            "message": "user not found... please try again",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/bills/buy_betting": {
            "post": {
                "tags": [
                    "Bills"
                ],
                "summary": "Fund betting wallet",
                "operationId": "buyBetting",
                "description": "Funds a customer betting account. Amount must be between **₦500** and **₦100,000**.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "provider",
                                    "customer_id",
                                    "name",
                                    "amount",
                                    "tranx_id"
                                ],
                                "properties": {
                                    "provider": {
                                        "type": "string",
                                        "description": "Provider identifier from List betting providers.",
                                        "example": "BET9JA"
                                    },
                                    "customer_id": {
                                        "type": "string",
                                        "description": "Customer ID on the betting platform.",
                                        "example": "1234567"
                                    },
                                    "name": {
                                        "type": "string",
                                        "description": "Account name from Resolve betting account.",
                                        "example": "ADEBAYO OLUWASEUN"
                                    },
                                    "amount": {
                                        "type": "number",
                                        "description": "Amount in naira, 500 to 100,000.",
                                        "minimum": 500,
                                        "maximum": 100000,
                                        "example": 5000
                                    },
                                    "tranx_id": {
                                        "type": "string",
                                        "description": "Your unique reference for this request. Can only be used once.",
                                        "example": "ACME-20261121-000188"
                                    }
                                }
                            },
                            "example": {
                                "provider": "BET9JA",
                                "customer_id": "1234567",
                                "name": "ADEBAYO OLUWASEUN",
                                "amount": 5000,
                                "tranx_id": "ACME-20261121-000188"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Funded or queued",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "success": {
                                        "summary": "Funded",
                                        "value": {
                                            "status": "success",
                                            "message": "Your Betting Funding To 1234567 Was Successful... Thank You",
                                            "data": {
                                                "id": 81234,
                                                "tranx_status": 1,
                                                "order_id": "ACME-20261121-000184",
                                                "tranx_type": 25,
                                                "network": "BET9JA",
                                                "amount": "5000.00",
                                                "charge": "0.00",
                                                "phone": "1234567",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"249,000.0000\"}",
                                                "created_at": "2026-11-21 10:15:02",
                                                "updated_at": "2026-11-21 10:15:02",
                                                "percent": "0",
                                                "channel": "APP",
                                                "app_meta_data": null
                                            }
                                        }
                                    },
                                    "queued": {
                                        "summary": "Still processing",
                                        "value": {
                                            "status": "success",
                                            "message": "Betting Funding Queued...",
                                            "data": {
                                                "id": 81234,
                                                "tranx_status": 1,
                                                "order_id": "ACME-20261121-000184",
                                                "tranx_type": 25,
                                                "network": "BET9JA",
                                                "amount": "5000.00",
                                                "charge": "0.00",
                                                "phone": "1234567",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"249,000.0000\"}",
                                                "created_at": "2026-11-21 10:15:02",
                                                "updated_at": "2026-11-21 10:15:02",
                                                "percent": "0",
                                                "channel": "APP",
                                                "app_meta_data": null
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "417": {
                        "description": "Rejected",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "reversed": {
                                        "summary": "Failed and refunded",
                                        "value": {
                                            "status": "failed",
                                            "message": "Betting Purchase Failed And Reversed",
                                            "data": {
                                                "id": 81234,
                                                "tranx_status": 1,
                                                "order_id": "ACME-20261121-000184",
                                                "tranx_type": 25,
                                                "network": "BET9JA",
                                                "amount": "5000.00",
                                                "charge": "0.00",
                                                "phone": "1234567",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"249,000.0000\"}",
                                                "created_at": "2026-11-21 10:15:02",
                                                "updated_at": "2026-11-21 10:15:02",
                                                "percent": "0",
                                                "channel": "APP",
                                                "app_meta_data": null
                                            }
                                        }
                                    },
                                    "limits": {
                                        "summary": "Outside the allowed range",
                                        "value": {
                                            "status": "failed",
                                            "message": "minimum funding amount is NGN500",
                                            "data": null
                                        }
                                    },
                                    "duplicate": {
                                        "summary": "The tranx_id was already used",
                                        "value": {
                                            "status": "failed",
                                            "message": "duplicate transaction detected....",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/bills/verify_transaction": {
            "get": {
                "tags": [
                    "Bills"
                ],
                "summary": "Verify bill",
                "operationId": "verifyBill",
                "description": "Returns the final status of a bill payment by your `tranx_id`. Use this for every queued purchase and before retrying.\n\n| HTTP | Meaning |\n|---|---|\n| `200` | Successful |\n| `400` | Still pending, check again later |\n| `417` | Failed and refunded to your wallet |\n| `404` | No bill with this `tranx_id` |",
                "parameters": [
                    {
                        "name": "tranx_id",
                        "in": "query",
                        "required": true,
                        "description": "The `tranx_id` you sent when buying.",
                        "schema": {
                            "type": "string",
                            "minLength": 10
                        },
                        "example": "ACME-20261121-000184"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "success": {
                                        "summary": "Delivered",
                                        "value": {
                                            "status": "success",
                                            "message": "transaction successful",
                                            "data": {
                                                "order_id": "ACME-20261121-000184",
                                                "network": "MTN",
                                                "amount": "1000.00",
                                                "charge": "0.00",
                                                "phone": "08031234567",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"249,000.0000\"}",
                                                "created_at": "2026-11-21 10:15:02",
                                                "updated_at": "2026-11-21 10:15:02",
                                                "percent": "0",
                                                "channel": "APP",
                                                "app_meta_data": null,
                                                "tranx_name": "AIRTIME PURCHASE",
                                                "status_name": "SUCCESSFUL",
                                                "bill_tranx_id": 81234
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "417": {
                        "description": "Failed and refunded",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "reversed": {
                                        "summary": "Refunded to wallet",
                                        "value": {
                                            "status": "failed",
                                            "message": "transaction faield... reverse record",
                                            "data": {
                                                "order_id": "ACME-20261121-000184",
                                                "network": "MTN",
                                                "amount": "1000.00",
                                                "charge": "0.00",
                                                "phone": "08031234567",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"249,000.0000\"}",
                                                "created_at": "2026-11-21 10:15:02",
                                                "updated_at": "2026-11-21 10:15:02",
                                                "percent": "0",
                                                "channel": "APP",
                                                "app_meta_data": null,
                                                "tranx_name": "AIRTIME PURCHASE",
                                                "status_name": "REVERSED",
                                                "bill_tranx_id": 81234
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "Unknown tranx_id",
                                        "value": {
                                            "status": "failed",
                                            "message": "no record found",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    },
                                    "pending": {
                                        "summary": "Still pending",
                                        "value": {
                                            "status": "failed",
                                            "message": "transactionf still pending....",
                                            "data": {
                                                "order_id": "ACME-20261121-000184",
                                                "network": "MTN",
                                                "amount": "1000.00",
                                                "charge": "0.00",
                                                "phone": "08031234567",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"249,000.0000\"}",
                                                "created_at": "2026-11-21 10:15:02",
                                                "updated_at": "2026-11-21 10:15:02",
                                                "percent": "0",
                                                "channel": "APP",
                                                "app_meta_data": null,
                                                "tranx_name": "AIRTIME PURCHASE",
                                                "status_name": "PENDING",
                                                "bill_tranx_id": 81234
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/bills/get_all_transaction": {
            "get": {
                "tags": [
                    "Bills"
                ],
                "summary": "List transactions",
                "operationId": "listTransactions",
                "description": "Returns your recent transactions across collections, transfers and bills, newest first. Results are cached for about 20 seconds.",
                "responses": {
                    "200": {
                        "description": "Transactions",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "list": {
                                        "summary": "Recent activity",
                                        "value": {
                                            "status": "success",
                                            "message": "successful",
                                            "data": [
                                                {
                                                    "tranx_name": "AIRTIME PURCHASE",
                                                    "status_name": "SUCCESSFUL",
                                                    "tranx_status": 2,
                                                    "bank_name": null,
                                                    "tranx_id": "ACME-20261121-000185",
                                                    "transaction_amount": "1000.00",
                                                    "settled_amount": null,
                                                    "processing_fee": null,
                                                    "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"249,000.0000\"}",
                                                    "tranx_type": 2,
                                                    "meta_data": null,
                                                    "percent": "0",
                                                    "created_at": "2026-11-21 10:15:02"
                                                },
                                                {
                                                    "tranx_name": "INCOMING TRANSFER",
                                                    "status_name": "SUCCESSFUL",
                                                    "tranx_status": 2,
                                                    "bank_name": "GTBANK",
                                                    "tranx_id": "INV-10045",
                                                    "transaction_amount": "25000.00",
                                                    "settled_amount": "24900.00",
                                                    "processing_fee": "100.00",
                                                    "balance_state": "{\"balance_before\":\"225,100.0000\",\"balance_after\":\"250,000.0000\"}",
                                                    "tranx_type": 1,
                                                    "meta_data": null,
                                                    "percent": null,
                                                    "created_at": "2026-11-21 09:58:40"
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/payment/generate_business_account_v2": {
            "post": {
                "tags": [
                    "Collections"
                ],
                "summary": "Create static account",
                "operationId": "createStaticAccount",
                "description": "Creates a permanent bank account number (Rubies MFB) for your business. Every transfer into it is credited to your wallet and reported to your webhook.\n\nCalling it again returns your existing account.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "account_name"
                                ],
                                "properties": {
                                    "account_name": {
                                        "type": "string",
                                        "description": "Name to show on the account, at least 5 characters.",
                                        "minLength": 5,
                                        "example": "ACME STORES"
                                    }
                                }
                            },
                            "example": {
                                "account_name": "ACME STORES"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Account",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "created": {
                                        "summary": "Static account",
                                        "value": {
                                            "status": "success",
                                            "message": "wallet generated successfully",
                                            "data": {
                                                "account_name": "SENDCHEAP(ACME STORES)",
                                                "account_number": "9876543210",
                                                "bank_name": "Rubies MFB"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "417": {
                        "description": "Not enabled",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "not_onboarded": {
                                        "summary": "Your business is not enabled for this product",
                                        "value": {
                                            "status": "failed",
                                            "message": "you are not onboarded for this service... contact support",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/payment/update_account_number_name": {
            "post": {
                "tags": [
                    "Collections"
                ],
                "summary": "Rename account",
                "operationId": "renameAccount",
                "description": "Changes the display name on one of your account numbers. The bank shows it as `SENDCHEAP(<account_name>)`.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "account_number",
                                    "account_name"
                                ],
                                "properties": {
                                    "account_number": {
                                        "type": "string",
                                        "description": "One of your SendCheap account numbers.",
                                        "minLength": 10,
                                        "example": "9876543210"
                                    },
                                    "account_name": {
                                        "type": "string",
                                        "description": "New name, at least 3 characters.",
                                        "minLength": 3,
                                        "example": "ACME HOLDINGS"
                                    }
                                }
                            },
                            "example": {
                                "account_number": "9876543210",
                                "account_name": "ACME HOLDINGS"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Renamed",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "renamed": {
                                        "summary": "Updated",
                                        "value": {
                                            "status": "success",
                                            "message": "account number updated successfully",
                                            "data": {
                                                "account_number": "9876543210",
                                                "account_name": "SENDCHEAP(ACME HOLDINGS)"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/payment/generate_dynamic_account_v2": {
            "post": {
                "tags": [
                    "Collections"
                ],
                "summary": "Create invoice account",
                "operationId": "createInvoiceAccount",
                "description": "Creates a bank account number (Rubies MFB) for one invoice, so you know exactly which order a payment belongs to.\n\n- Send your own **`invoice_id`** (max 50 characters). It identifies the payment in webhooks and verification.\n- **`tranx_amount`** is the amount you expect, in naira. It must be higher than your collection fee.\n- If the invoice was **already paid**, you get HTTP `201` and the settlement webhook is sent again.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "invoice_id",
                                    "tranx_amount",
                                    "account_name"
                                ],
                                "properties": {
                                    "invoice_id": {
                                        "type": "string",
                                        "description": "Your unique invoice/order reference, 5 to 50 characters.",
                                        "minLength": 5,
                                        "maxLength": 50,
                                        "example": "INV-10045"
                                    },
                                    "tranx_amount": {
                                        "type": "string",
                                        "description": "Expected amount in naira, as a numeric string. Must be higher than your collection fee.",
                                        "example": "25000"
                                    },
                                    "account_name": {
                                        "type": "string",
                                        "description": "Name shown to the payer, at least 5 characters.",
                                        "minLength": 5,
                                        "example": "JOHN DOE"
                                    }
                                }
                            },
                            "example": {
                                "invoice_id": "INV-10045",
                                "tranx_amount": "25000",
                                "account_name": "JOHN DOE"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Account for this invoice",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "created": {
                                        "summary": "Invoice account",
                                        "value": {
                                            "status": "success",
                                            "message": "account number generated",
                                            "data": {
                                                "account_name": "ACME STORES - JOHN DOE",
                                                "account_number": "9876501234",
                                                "invoice_id": "INV-10045",
                                                "tranx_amount": "25000",
                                                "settled_amount": 0
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "Already paid",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "paid": {
                                        "summary": "Invoice already settled",
                                        "value": {
                                            "status": "success",
                                            "message": "transaction with this invoice has been paid and processed successfully.",
                                            "data": []
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/payment/verify_transaction": {
            "get": {
                "tags": [
                    "Collections"
                ],
                "summary": "Verify invoice",
                "operationId": "verifyInvoice",
                "description": "Checks whether an invoice account has received payment. Call this before giving value, even after a webhook.",
                "parameters": [
                    {
                        "name": "invoice_id",
                        "in": "query",
                        "required": true,
                        "description": "Your invoice reference.",
                        "schema": {
                            "type": "string",
                            "minLength": 5
                        },
                        "example": "INV-10045"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paid",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "paid": {
                                        "summary": "Payment received",
                                        "value": {
                                            "status": "success",
                                            "message": "transaction confirm successfully",
                                            "data": []
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    },
                                    "pending": {
                                        "summary": "Not paid yet",
                                        "value": {
                                            "status": "failed",
                                            "message": "payment still pending",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/payment/verify_transaction_by_session_id": {
            "get": {
                "tags": [
                    "Collections"
                ],
                "summary": "Verify by session ID",
                "operationId": "verifyBySession",
                "description": "Finds an incoming transfer by its NIBSS session ID (shown on the payer's receipt).",
                "parameters": [
                    {
                        "name": "session_id",
                        "in": "query",
                        "required": true,
                        "description": "NIBSS session ID of the transfer.",
                        "schema": {
                            "type": "string",
                            "minLength": 5
                        },
                        "example": "100004261121095840123456789012"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "found": {
                                        "summary": "Incoming transfer",
                                        "value": {
                                            "status": "success",
                                            "message": "transaction confirm successfully",
                                            "data": {
                                                "id": 55120,
                                                "tranx_type": 1,
                                                "bank_name": "GTBANK",
                                                "settlement_id": "INV-10045",
                                                "session_id": "100004261121095840123456789012",
                                                "transaction_amount": "25000.00",
                                                "settled_amount": "24900.00",
                                                "fee_amount": "100.00",
                                                "vat_amount": "0.00",
                                                "currency": "NGN",
                                                "balance_state": "{\"balance_before\":\"225,100.0000\",\"balance_after\":\"250,000.0000\"}",
                                                "created_at": "2026-11-21 09:58:40",
                                                "temp_invoice": "INV-10045",
                                                "processing_fee": "100.00",
                                                "receiving_account_number": "9876501234",
                                                "channel": 22,
                                                "payment_channel": "APP"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    },
                                    "not_found": {
                                        "summary": "Unknown session",
                                        "value": {
                                            "status": "failed",
                                            "message": "transaction not found",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/payment/repush_notification": {
            "get": {
                "tags": [
                    "Collections"
                ],
                "summary": "Resend webhook",
                "operationId": "resendWebhook",
                "description": "Sends the payment webhook for an invoice again. Use it if your server missed or rejected the first delivery.",
                "parameters": [
                    {
                        "name": "invoice_id",
                        "in": "query",
                        "required": true,
                        "description": "Your invoice reference.",
                        "schema": {
                            "type": "string",
                            "minLength": 5
                        },
                        "example": "INV-10045"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Sent",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "sent": {
                                        "summary": "Webhook delivered",
                                        "value": {
                                            "status": "success",
                                            "message": "payemnt confirmed successfully...",
                                            "data": []
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/payment/get_money_received_transaction": {
            "get": {
                "tags": [
                    "Collections"
                ],
                "summary": "List payments received",
                "operationId": "listReceived",
                "description": "Lists incoming transfers, newest first, 5 per page. Use `cursor` as the page number starting at 0.",
                "parameters": [
                    {
                        "name": "cursor",
                        "in": "query",
                        "required": true,
                        "description": "Page number, starting at 0.",
                        "schema": {
                            "type": "integer",
                            "minimum": 0
                        },
                        "example": 0
                    },
                    {
                        "name": "search_key",
                        "in": "query",
                        "required": false,
                        "description": "Optional. Filter by invoice, session ID or account number.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "INV-10045"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Payments",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "list": {
                                        "summary": "Page of payments",
                                        "value": {
                                            "status": "success",
                                            "message": "transaction retreved successfully",
                                            "data": [
                                                {
                                                    "id": 55120,
                                                    "tranx_type": 1,
                                                    "bank_name": "GTBANK",
                                                    "settlement_id": "INV-10045",
                                                    "session_id": "100004261121095840123456789012",
                                                    "transaction_amount": "25000.00",
                                                    "settled_amount": "24900.00",
                                                    "fee_amount": "100.00",
                                                    "vat_amount": "0.00",
                                                    "currency": "NGN",
                                                    "balance_state": "{\"balance_before\":\"225,100.0000\",\"balance_after\":\"250,000.0000\"}",
                                                    "created_at": "2026-11-21 09:58:40",
                                                    "temp_invoice": "INV-10045",
                                                    "processing_fee": "100.00",
                                                    "receiving_account_number": "9876501234",
                                                    "channel": 22,
                                                    "payment_channel": "APP",
                                                    "tranx_name": "INCOMING TRANSFER"
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/payment/get_wallet_balance": {
            "get": {
                "tags": [
                    "Collections"
                ],
                "summary": "Get balance",
                "operationId": "getBalance",
                "description": "Returns your NGN wallet balance and settlement account.",
                "responses": {
                    "200": {
                        "description": "Balance",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "balance": {
                                        "summary": "Wallet",
                                        "value": {
                                            "status": "success",
                                            "message": "successful",
                                            "data": {
                                                "account_number": "9876543210",
                                                "account_name": "SENDCHEAP(ACME STORES)",
                                                "ngn_balance": "250000.00",
                                                "ngn_fronzen": "0.00",
                                                "usd_balance": "0.00",
                                                "usd_fronzen": "0.00",
                                                "updated_at": "2026-11-21 10:15:02",
                                                "tier_account": "BUSINESS",
                                                "bank_name": "Rubies MFB"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/payment/get_bank_list": {
            "get": {
                "tags": [
                    "Transfers"
                ],
                "summary": "List banks",
                "operationId": "listBanks",
                "description": "Returns Nigerian banks and their `bank_code`. Use `999999` as `bank_code` for a SendCheap account. Cache the list on your side.",
                "responses": {
                    "200": {
                        "description": "Banks",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "banks": {
                                        "summary": "Bank list",
                                        "value": {
                                            "status": "success",
                                            "message": "Retrieved Successfully",
                                            "data": [
                                                {
                                                    "bank_name": "GTBANK PLC",
                                                    "bank_code": "000013",
                                                    "bank_logo": "https://api.sendcheap.us/public/bank_logo/gtb.png"
                                                },
                                                {
                                                    "bank_name": "ACCESS BANK",
                                                    "bank_code": "000014",
                                                    "bank_logo": "https://api.sendcheap.us/public/bank_logo/access.png"
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/payment/resolve_transfer": {
            "post": {
                "tags": [
                    "Transfers"
                ],
                "summary": "Resolve account",
                "operationId": "resolveAccount",
                "description": "Looks up the account name for a bank account. Always show it to your user before sending money.\\n\\nKeep `client_Id`, `bank_Id` and `client_bvn` from this response: Send transfer needs them as `client_id`, `bank_id` and `client_bvn`.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "account_number",
                                    "bank_code"
                                ],
                                "properties": {
                                    "account_number": {
                                        "type": "string",
                                        "description": "10-digit account number.",
                                        "minLength": 10,
                                        "example": "0123456789"
                                    },
                                    "bank_code": {
                                        "type": "string",
                                        "description": "`bank_code` from List banks.",
                                        "minLength": 4,
                                        "example": "000013"
                                    }
                                }
                            },
                            "example": {
                                "account_number": "0123456789",
                                "bank_code": "000013"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Account found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "bank": {
                                        "summary": "Account at another bank",
                                        "value": {
                                            "status": "success",
                                            "message": "Retrieved Successfully",
                                            "data": {
                                                "sendcheap_user": false,
                                                "account_name": "JOHN DOE",
                                                "account_number": "0123456789",
                                                "bank_name": "GTBANK PLC",
                                                "client_bvn": "22212345678",
                                                "bank_code": "000013",
                                                "client_Id": "341256",
                                                "bank_Id": "058NIP2611211030"
                                            }
                                        }
                                    },
                                    "sendcheap": {
                                        "summary": "A SendCheap account",
                                        "value": {
                                            "status": "success",
                                            "message": "Retrieved Successfully",
                                            "data": {
                                                "sendcheap_user": true,
                                                "account_name": "SENDCHEAP(JANE STORES)",
                                                "bank_name": "SendCheap LTD",
                                                "account_number": "9876500000",
                                                "username": "janestores"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    },
                                    "not_found": {
                                        "summary": "Account not found",
                                        "value": {
                                            "status": "failed",
                                            "message": "account not found",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/payment/transfer_funds": {
            "post": {
                "tags": [
                    "Transfers"
                ],
                "summary": "Send transfer",
                "operationId": "sendTransfer",
                "description": "Sends money from your NGN wallet to a bank account. Minimum **₦100**. Your transfer fee is added to the amount, plus **₦50 stamp duty** on transfers of ₦10,000 or more.\n\nCall **Resolve account** first and pass its `client_Id`, `bank_Id` and `client_bvn`.\n\n- **`200`** — sent.\n- **`206 Transfer Queued`** — accepted but not yet confirmed. Poll **Verify transfer** with your `tranx_id`.\n- Never resend with a new `tranx_id` until Verify transfer shows the first one failed.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "amount",
                                    "account_number",
                                    "account_name",
                                    "bank_name",
                                    "bank_code",
                                    "bank_id",
                                    "tranx_remark",
                                    "client_id",
                                    "client_bvn",
                                    "tranx_id"
                                ],
                                "properties": {
                                    "amount": {
                                        "type": "number",
                                        "description": "Amount in naira. Minimum 100.",
                                        "minimum": 100,
                                        "example": 25000
                                    },
                                    "account_number": {
                                        "type": "string",
                                        "description": "Destination account number.",
                                        "minLength": 10,
                                        "example": "0123456789"
                                    },
                                    "account_name": {
                                        "type": "string",
                                        "description": "Account name from Resolve account.",
                                        "example": "JOHN DOE"
                                    },
                                    "bank_name": {
                                        "type": "string",
                                        "description": "Bank name from List banks.",
                                        "example": "GTBANK PLC"
                                    },
                                    "bank_code": {
                                        "type": "string",
                                        "description": "`bank_code` from List banks.",
                                        "minLength": 4,
                                        "example": "000013"
                                    },
                                    "bank_id": {
                                        "type": "string",
                                        "description": "`bank_Id` from Resolve account.",
                                        "minLength": 3,
                                        "example": "058NIP2611211030"
                                    },
                                    "tranx_remark": {
                                        "type": "string",
                                        "description": "Narration shown to the recipient, at least 4 characters.",
                                        "minLength": 4,
                                        "example": "Order 10045 refund"
                                    },
                                    "client_id": {
                                        "type": "string",
                                        "description": "`client_Id` from Resolve account (empty string if it returned none).",
                                        "example": "341256"
                                    },
                                    "client_bvn": {
                                        "type": "string",
                                        "description": "`client_bvn` from Resolve account (empty string if it returned none).",
                                        "example": "22212345678"
                                    },
                                    "tranx_id": {
                                        "type": "string",
                                        "description": "Your unique reference for this request, at least 10 characters. A reference can only be used once; reusing it returns \"duplicate transaction detected\". Store it so you can verify the transaction later.",
                                        "minLength": 10,
                                        "example": "ACME-20261121-000184"
                                    }
                                }
                            },
                            "example": {
                                "amount": 25000,
                                "account_number": "0123456789",
                                "account_name": "JOHN DOE",
                                "bank_name": "GTBANK PLC",
                                "bank_code": "000013",
                                "bank_id": "058NIP2611211030",
                                "tranx_remark": "Order 10045 refund",
                                "client_id": "341256",
                                "client_bvn": "22212345678",
                                "tranx_id": "ACME-20261121-000190"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Sent",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "sent": {
                                        "summary": "Transfer successful",
                                        "value": {
                                            "status": "success",
                                            "message": "your transfer was successful...",
                                            "data": {
                                                "payment_response": "{\"responseCode\":\"00\",\"responseMessage\":\"Approved\"}",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"224,950.0000\"}"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "206": {
                        "description": "Queued",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "queued": {
                                        "summary": "Not confirmed yet",
                                        "value": {
                                            "status": "success",
                                            "message": "Transfer Queued",
                                            "data": {
                                                "payment_response": "{\"responseCode\":\"09\",\"responseMessage\":\"Pending\"}",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"224,950.0000\"}"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "417": {
                        "description": "Rejected",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "minimum": {
                                        "summary": "Below the minimum",
                                        "value": {
                                            "status": "failed",
                                            "message": "unable to perform transfer... Minimum transfer amount is (NGN100)",
                                            "data": null
                                        }
                                    },
                                    "low_balance": {
                                        "summary": "Not enough balance for amount + fee",
                                        "value": {
                                            "status": "failed",
                                            "message": "something went wrong... please try again...",
                                            "data": null
                                        }
                                    },
                                    "review": {
                                        "summary": "Account under review",
                                        "value": {
                                            "status": "failed",
                                            "message": "Your account needs a quick review before this transaction can be completed. Please contact support.",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/payment/verify_transfer": {
            "get": {
                "tags": [
                    "Transfers"
                ],
                "summary": "Verify transfer",
                "operationId": "verifyTransfer",
                "description": "Returns a transfer by your `tranx_id`. `tranx_status`: `1` pending, `2` successful, `3` failed and refunded.",
                "parameters": [
                    {
                        "name": "tranx_id",
                        "in": "query",
                        "required": true,
                        "description": "The `tranx_id` you sent.",
                        "schema": {
                            "type": "string",
                            "minLength": 10
                        },
                        "example": "ACME-20261121-000190"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Transfer",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "found": {
                                        "summary": "Transfer record",
                                        "value": {
                                            "status": "success",
                                            "message": "transfer transaction retrieved...",
                                            "data": {
                                                "tranx_status": 2,
                                                "bank_name": "GTBANK PLC",
                                                "beneficiary_account_number": "0123456789",
                                                "beneficiary_account_name": "JOHN DOE",
                                                "bank_code": "000013",
                                                "amount": "25000.00",
                                                "charge": "50.00",
                                                "tranx_remark": "Order 10045 refund",
                                                "balance_state": "{\"balance_before\":\"250,000.0000\",\"balance_after\":\"224,950.0000\"}",
                                                "meta_data": null,
                                                "created_at": "2026-11-21 10:30:11",
                                                "updated_at": "2026-11-21 10:30:14",
                                                "channel": "APP",
                                                "tranx_id": "ACME-20261121-000190"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    },
                                    "not_found": {
                                        "summary": "Unknown tranx_id",
                                        "value": {
                                            "status": "failed",
                                            "message": "transaction not found... please try again.",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/crypto/get_supported_coin": {
            "get": {
                "tags": [
                    "Crypto"
                ],
                "summary": "List coins",
                "operationId": "listCoins",
                "description": "Returns the cryptocurrencies you can receive and send. `price_data` holds the current NGN sell price.",
                "responses": {
                    "200": {
                        "description": "Coins",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "coins": {
                                        "summary": "Supported coins",
                                        "value": {
                                            "status": "success",
                                            "message": "Supported coins retrieved",
                                            "data": [
                                                {
                                                    "id": 3,
                                                    "name": "Tether",
                                                    "symbol": "USDT",
                                                    "status": 1,
                                                    "is_fiat": 0,
                                                    "withdraw_fee": "0.5",
                                                    "price_data": {}
                                                },
                                                {
                                                    "id": 1,
                                                    "name": "Bitcoin",
                                                    "symbol": "BTC",
                                                    "status": 1,
                                                    "is_fiat": 0,
                                                    "withdraw_fee": "0.5",
                                                    "price_data": {}
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "417": {
                        "description": "Not enabled",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "not_onboarded": {
                                        "summary": "Your business is not enabled for this product",
                                        "value": {
                                            "status": "failed",
                                            "message": "you are not onboarded for this service... contact support",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/crypto/get_network": {
            "get": {
                "tags": [
                    "Crypto"
                ],
                "summary": "List networks",
                "operationId": "listNetworks",
                "description": "Returns the blockchain networks for a coin, with withdrawal fee and minimum. Use `networkCode` as `network` elsewhere.",
                "parameters": [
                    {
                        "name": "coin_symbol",
                        "in": "query",
                        "required": true,
                        "description": "Coin symbol from List coins.",
                        "schema": {
                            "type": "string",
                            "minLength": 2
                        },
                        "example": "USDT"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Networks",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "networks": {
                                        "summary": "USDT networks",
                                        "value": {
                                            "status": "success",
                                            "message": "Supported coins retrieved",
                                            "data": [
                                                {
                                                    "networkCode": "TRX",
                                                    "networkName": "Tron (TRC20)",
                                                    "withdrawalFee": 1,
                                                    "minimumWithdrawal": 5
                                                },
                                                {
                                                    "networkCode": "BSC",
                                                    "networkName": "BNB Smart Chain (BEP20)",
                                                    "withdrawalFee": 0.299999999999999988897769753748434595763683319091796875,
                                                    "minimumWithdrawal": 2
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/crypto/generate_crypto_wallet": {
            "get": {
                "tags": [
                    "Crypto"
                ],
                "summary": "Get deposit address",
                "operationId": "getDepositAddress",
                "description": "Returns a deposit address for one of your customers on a network. The same `partner_user_id` and network always return the same address.\n\nDeposits are credited to your crypto balance and reported to your webhook.",
                "parameters": [
                    {
                        "name": "symbol",
                        "in": "query",
                        "required": true,
                        "description": "Coin symbol.",
                        "schema": {
                            "type": "string",
                            "minLength": 3
                        },
                        "example": "USDT"
                    },
                    {
                        "name": "network",
                        "in": "query",
                        "required": true,
                        "description": "`networkCode` from List networks.",
                        "schema": {
                            "type": "string",
                            "minLength": 2
                        },
                        "example": "TRX"
                    },
                    {
                        "name": "partner_user_id",
                        "in": "query",
                        "required": true,
                        "description": "Your ID for the customer this address belongs to.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "CUS-883"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Address",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "address": {
                                        "summary": "Deposit address",
                                        "value": {
                                            "status": "success",
                                            "message": "wallet retrieved successfully",
                                            "data": {
                                                "id": 912,
                                                "partner_user_id": "CUS-883",
                                                "network": "TRX",
                                                "address": "TXa1b2c3d4e5f6g7h8i9j0kLmNoPqRsTuV",
                                                "created_at": "2026-11-21 11:02:00",
                                                "updated_at": "2026-11-21 11:02:00",
                                                "deleted": 0
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "417": {
                        "description": "Not enabled",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "not_onboarded": {
                                        "summary": "Your business is not enabled for this product",
                                        "value": {
                                            "status": "failed",
                                            "message": "you are not onboarded for this service... contact support",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/crypto/transfer_coin": {
            "post": {
                "tags": [
                    "Crypto"
                ],
                "summary": "Send crypto",
                "operationId": "sendCrypto",
                "description": "Sends crypto from your balance to an external wallet. The network fee plus SendCheap's withdrawal fee are deducted from the amount.\n\nThis endpoint has **no idempotency key**. If a request times out, check **List crypto transactions** before sending again.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "symbol",
                                    "network",
                                    "wallet",
                                    "transfer_amount"
                                ],
                                "properties": {
                                    "symbol": {
                                        "type": "string",
                                        "description": "Coin symbol.",
                                        "example": "USDT"
                                    },
                                    "network": {
                                        "type": "string",
                                        "description": "`networkCode` from List networks.",
                                        "example": "TRX"
                                    },
                                    "wallet": {
                                        "type": "string",
                                        "description": "Destination wallet address.",
                                        "example": "TXz9y8x7w6v5u4t3s2r1qPoNmLkJiHgFeD"
                                    },
                                    "transfer_amount": {
                                        "type": "number",
                                        "description": "Amount of the coin to send. Must be at least the network minimum.",
                                        "example": 50
                                    }
                                }
                            },
                            "example": {
                                "symbol": "USDT",
                                "network": "TRX",
                                "wallet": "TXz9y8x7w6v5u4t3s2r1qPoNmLkJiHgFeD",
                                "transfer_amount": 50
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Sent or queued",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "sent": {
                                        "summary": "Sent",
                                        "value": {
                                            "status": "success",
                                            "message": "transfer successul",
                                            "data": []
                                        }
                                    },
                                    "queued": {
                                        "summary": "Queued at the provider",
                                        "value": {
                                            "status": "success",
                                            "message": "transfer qued successfully",
                                            "data": []
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    },
                                    "insufficient": {
                                        "summary": "Not enough balance",
                                        "value": {
                                            "status": "failed",
                                            "message": "insufficient balance...",
                                            "data": null
                                        }
                                    },
                                    "minimum": {
                                        "summary": "Below network minimum",
                                        "value": {
                                            "status": "failed",
                                            "message": "minimum transfer amount is 5USDT",
                                            "data": null
                                        }
                                    },
                                    "network": {
                                        "summary": "Unknown network",
                                        "value": {
                                            "status": "failed",
                                            "message": "invalid network selected...",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/crypto/get_all_crypto_transaction": {
            "get": {
                "tags": [
                    "Crypto"
                ],
                "summary": "List crypto transactions",
                "operationId": "listCryptoTransactions",
                "description": "Returns your crypto deposits and withdrawals, newest first.",
                "responses": {
                    "200": {
                        "description": "Transactions",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "list": {
                                        "summary": "Crypto activity",
                                        "value": {
                                            "status": "success",
                                            "message": "Tranaction received",
                                            "data": [
                                                {
                                                    "id": 7781,
                                                    "tranx_status": 2,
                                                    "amount": "50.00000000",
                                                    "fee_ngn": "0.00",
                                                    "tranx_id": "CRYPTO-6abf4fff1d2a",
                                                    "meta_data": "{\"address\":\"TXa1b2c3d4e5f6g7h8i9j0kLmNoPqRsTuV\",\"network\":\"TRX\",\"currency\":\"USDT\",\"hash\":\"0f3c9b2e...\"}",
                                                    "balance_state": "{\"balance_before\":\"120.0000\",\"balance_after\":\"170.0000\"}",
                                                    "created_at": "2026-11-21 11:20:45",
                                                    "updated_at": "2026-11-21 11:20:45"
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "417": {
                        "description": "Not enabled",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "not_onboarded": {
                                        "summary": "Your business is not enabled for this product",
                                        "value": {
                                            "status": "failed",
                                            "message": "you are not onboarded for this service... contact support",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/crypto/get_transaction_by_id": {
            "get": {
                "tags": [
                    "Crypto"
                ],
                "summary": "Get crypto transaction",
                "operationId": "getCryptoTransaction",
                "description": "Returns one crypto transaction by its ID.",
                "parameters": [
                    {
                        "name": "invoice_id",
                        "in": "query",
                        "required": true,
                        "description": "The crypto transaction ID (`tranx_id`).",
                        "schema": {
                            "type": "string",
                            "minLength": 5
                        },
                        "example": "CRYPTO-6abf4fff1d2a"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Transaction",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "found": {
                                        "summary": "Crypto transaction",
                                        "value": {
                                            "status": "success",
                                            "message": "Tranaction received",
                                            "data": {
                                                "id": 7781,
                                                "tranx_status": 2,
                                                "amount": "50.00000000",
                                                "fee_ngn": "0.00",
                                                "tranx_id": "CRYPTO-6abf4fff1d2a",
                                                "meta_data": "{\"address\":\"TXa1b2c3d4e5f6g7h8i9j0kLmNoPqRsTuV\",\"network\":\"TRX\",\"currency\":\"USDT\",\"hash\":\"0f3c9b2e...\"}",
                                                "balance_state": "{\"balance_before\":\"120.0000\",\"balance_after\":\"170.0000\"}",
                                                "created_at": "2026-11-21 11:20:45",
                                                "updated_at": "2026-11-21 11:20:45"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/crypto/repush_settlement": {
            "get": {
                "tags": [
                    "Crypto"
                ],
                "summary": "Resend crypto webhook",
                "operationId": "resendCryptoWebhook",
                "description": "Sends the deposit webhook for a crypto transaction again.",
                "parameters": [
                    {
                        "name": "invoice_id",
                        "in": "query",
                        "required": true,
                        "description": "The crypto transaction ID.",
                        "schema": {
                            "type": "string",
                            "minLength": 5
                        },
                        "example": "CRYPTO-6abf4fff1d2a"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Sent",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "sent": {
                                        "summary": "Webhook delivered",
                                        "value": {
                                            "status": "success",
                                            "message": "webhook sent",
                                            "data": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Your server did not accept it",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "rejected": {
                                        "summary": "Webhook endpoint did not reply with success",
                                        "value": {
                                            "status": "failed",
                                            "message": "please try again.. Thank you",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/payment/get_crypto_wallet_balance": {
            "get": {
                "tags": [
                    "Crypto"
                ],
                "summary": "Get crypto balance",
                "operationId": "getCryptoBalance",
                "description": "Returns your balance for each coin.",
                "responses": {
                    "200": {
                        "description": "Balances",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "balances": {
                                        "summary": "Coin balances",
                                        "value": {
                                            "status": "success",
                                            "message": "business crypto balance retrieved",
                                            "data": [
                                                {
                                                    "id": 3,
                                                    "name": "Tether",
                                                    "symbol": "USDT",
                                                    "balance": "170.00000000"
                                                },
                                                {
                                                    "id": 1,
                                                    "name": "Bitcoin",
                                                    "symbol": "BTC",
                                                    "balance": "0.00125000"
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/kyc/verify_bvn": {
            "post": {
                "tags": [
                    "KYC"
                ],
                "summary": "Look up BVN",
                "operationId": "verifyBvn",
                "description": "Returns the BVN holder details. `firstname` and `lastname` are accepted but optional (send empty strings). Each call is charged.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "bvn",
                                    "firstname",
                                    "lastname",
                                    "tranx_id"
                                ],
                                "properties": {
                                    "bvn": {
                                        "type": "string",
                                        "description": "11-digit Bank Verification Number.",
                                        "minLength": 10,
                                        "example": "22212345678"
                                    },
                                    "firstname": {
                                        "type": "string",
                                        "description": "First name to match against the BVN record.",
                                        "example": "Adebayo"
                                    },
                                    "lastname": {
                                        "type": "string",
                                        "description": "Last name to match against the BVN record.",
                                        "example": "Oluwaseun"
                                    },
                                    "tranx_id": {
                                        "type": "string",
                                        "description": "Your unique reference for this request, at least 10 characters. A reference can only be used once; reusing it returns \"duplicate transaction detected\". Store it so you can verify the transaction later.",
                                        "minLength": 10,
                                        "example": "ACME-20261121-000184"
                                    }
                                }
                            },
                            "example": {
                                "bvn": "22212345678",
                                "firstname": "Adebayo",
                                "lastname": "Oluwaseun",
                                "tranx_id": "ACME-KYC-0000000101"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "BVN found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "found": {
                                        "summary": "BVN details",
                                        "value": {
                                            "status": "success",
                                            "message": "BVN retrieved successfully",
                                            "data": {
                                                "bvn_data": {
                                                    "id": 3051,
                                                    "bvn": "22212345678",
                                                    "bvn_data": {
                                                        "request_reference": "a1b2c3d4e5",
                                                        "infoId": 48211,
                                                        "bvn_number": "22212345678",
                                                        "name_on_card": "ADEBAYO OLUWASEUN",
                                                        "enrolment_branch": "IKEJA",
                                                        "enrolment_bank": "058",
                                                        "formatted_registration_date": "2014-06-03",
                                                        "level_of_account": "Level 2 - Medium Level Accounts",
                                                        "nin": null,
                                                        "watchlisted": "NO",
                                                        "verification_status": "VERIFIED",
                                                        "service_type": "BVN Full Details",
                                                        "personal_info": {
                                                            "first_name": "ADEBAYO",
                                                            "middle_name": "JOHN",
                                                            "last_name": "OLUWASEUN",
                                                            "full_name": "ADEBAYO JOHN OLUWASEUN",
                                                            "email": "adebayo@example.com",
                                                            "gender": "Male",
                                                            "phone_number": "08031234567",
                                                            "phone_number_2": null,
                                                            "date_of_birth": "12-Apr-1990",
                                                            "formatted_date_of_birth": "1990-04-12",
                                                            "lga_of_origin": "Ikeja",
                                                            "state_of_origin": "Lagos State",
                                                            "nationality": null,
                                                            "marital_status": "Single",
                                                            "image_url": "https://images.example.com/bvn/22212345678.jpg"
                                                        },
                                                        "residential_info": {
                                                            "state_of_residence": "Lagos State",
                                                            "lga_of_residence": null,
                                                            "residential_address": "12 Allen Avenue, Ikeja"
                                                        }
                                                    },
                                                    "bvn_image": "_BVN/22212345678.jpg",
                                                    "created_at": "2026-11-21 12:01:33"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "417": {
                        "description": "Rejected",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "not_onboarded": {
                                        "summary": "Your business is not enabled for this product",
                                        "value": {
                                            "status": "failed",
                                            "message": "you are not onboarded for this service... contact support",
                                            "data": null
                                        }
                                    },
                                    "duplicate": {
                                        "summary": "The tranx_id was already used",
                                        "value": {
                                            "status": "failed",
                                            "message": "duplicate transaction detected....",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    },
                                    "not_found": {
                                        "summary": "BVN not found",
                                        "value": {
                                            "status": "failed",
                                            "message": "BVN record not found. please contact support or try again.",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/kyc/verify_bvn_v2": {
            "post": {
                "tags": [
                    "KYC"
                ],
                "summary": "Look up BVN v2",
                "operationId": "verifyBvnV2",
                "description": "Same as Look up BVN, with only `bvn` and `tranx_id`. Each call is charged.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "bvn",
                                    "tranx_id"
                                ],
                                "properties": {
                                    "bvn": {
                                        "type": "string",
                                        "description": "11-digit Bank Verification Number.",
                                        "minLength": 10,
                                        "example": "22212345678"
                                    },
                                    "tranx_id": {
                                        "type": "string",
                                        "description": "Your unique reference for this request, at least 10 characters. A reference can only be used once; reusing it returns \"duplicate transaction detected\". Store it so you can verify the transaction later.",
                                        "minLength": 10,
                                        "example": "ACME-20261121-000184"
                                    }
                                }
                            },
                            "example": {
                                "bvn": "22212345678",
                                "tranx_id": "ACME-KYC-0000000101"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "BVN found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "found": {
                                        "summary": "BVN details",
                                        "value": {
                                            "status": "success",
                                            "message": "BVN retrieved successfully",
                                            "data": {
                                                "bvn_data": {
                                                    "id": 3051,
                                                    "bvn": "22212345678",
                                                    "bvn_data": {
                                                        "request_reference": "a1b2c3d4e5",
                                                        "infoId": 48211,
                                                        "bvn_number": "22212345678",
                                                        "name_on_card": "ADEBAYO OLUWASEUN",
                                                        "enrolment_branch": "IKEJA",
                                                        "enrolment_bank": "058",
                                                        "formatted_registration_date": "2014-06-03",
                                                        "level_of_account": "Level 2 - Medium Level Accounts",
                                                        "nin": null,
                                                        "watchlisted": "NO",
                                                        "verification_status": "VERIFIED",
                                                        "service_type": "BVN Full Details",
                                                        "personal_info": {
                                                            "first_name": "ADEBAYO",
                                                            "middle_name": "JOHN",
                                                            "last_name": "OLUWASEUN",
                                                            "full_name": "ADEBAYO JOHN OLUWASEUN",
                                                            "email": "adebayo@example.com",
                                                            "gender": "Male",
                                                            "phone_number": "08031234567",
                                                            "phone_number_2": null,
                                                            "date_of_birth": "12-Apr-1990",
                                                            "formatted_date_of_birth": "1990-04-12",
                                                            "lga_of_origin": "Ikeja",
                                                            "state_of_origin": "Lagos State",
                                                            "nationality": null,
                                                            "marital_status": "Single",
                                                            "image_url": "https://images.example.com/bvn/22212345678.jpg"
                                                        },
                                                        "residential_info": {
                                                            "state_of_residence": "Lagos State",
                                                            "lga_of_residence": null,
                                                            "residential_address": "12 Allen Avenue, Ikeja"
                                                        }
                                                    },
                                                    "bvn_image": "_BVN/22212345678.jpg",
                                                    "created_at": "2026-11-21 12:01:33"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "417": {
                        "description": "Rejected",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "not_onboarded": {
                                        "summary": "Your business is not enabled for this product",
                                        "value": {
                                            "status": "failed",
                                            "message": "you are not onboarded for this service... contact support",
                                            "data": null
                                        }
                                    },
                                    "duplicate": {
                                        "summary": "The tranx_id was already used",
                                        "value": {
                                            "status": "failed",
                                            "message": "duplicate transaction detected....",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    },
                                    "not_found": {
                                        "summary": "BVN not found",
                                        "value": {
                                            "status": "failed",
                                            "message": "BVN record not found. please contact support or try again.",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/kyc/verify_bvn_bool": {
            "post": {
                "tags": [
                    "KYC"
                ],
                "summary": "Match BVN name",
                "operationId": "matchBvnName",
                "description": "Checks that the first and last name match the BVN record. On a match it returns the stored record; note that `bvn_data` here is a **JSON string**, so decode it. Each call is charged.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "bvn",
                                    "firstname",
                                    "lastname",
                                    "tranx_id"
                                ],
                                "properties": {
                                    "bvn": {
                                        "type": "string",
                                        "description": "11-digit Bank Verification Number.",
                                        "minLength": 10,
                                        "example": "22212345678"
                                    },
                                    "firstname": {
                                        "type": "string",
                                        "description": "First name to match against the BVN record.",
                                        "example": "Adebayo"
                                    },
                                    "lastname": {
                                        "type": "string",
                                        "description": "Last name to match against the BVN record.",
                                        "example": "Oluwaseun"
                                    },
                                    "tranx_id": {
                                        "type": "string",
                                        "description": "Your unique reference for this request, at least 10 characters. A reference can only be used once; reusing it returns \"duplicate transaction detected\". Store it so you can verify the transaction later.",
                                        "minLength": 10,
                                        "example": "ACME-20261121-000184"
                                    }
                                }
                            },
                            "example": {
                                "bvn": "22212345678",
                                "firstname": "Adebayo",
                                "lastname": "Oluwaseun",
                                "tranx_id": "ACME-KYC-0000000101"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Names match",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "match": {
                                        "summary": "Match",
                                        "value": {
                                            "status": "success",
                                            "message": "name matching was successful",
                                            "data": {
                                                "bvn_data": "{\"request_reference\":\"a1b2c3d4e5\",\"infoId\":48211,\"bvn_number\":\"22212345678\",\"name_on_card\":\"ADEBAYO OLUWASEUN\",\"enrolment_branch\":\"IKEJA\",\"enrolment_bank\":\"058\",\"formatted_registration_date\":\"2014-06-03\",\"level_of_account\":\"Level 2 - Medium Level Accounts\",\"nin\":null,\"watchlisted\":\"NO\",\"verification_status\":\"VERIFIED\",\"service_type\":\"BVN Full Details\",\"personal_info\":{\"first_name\":\"ADEBAYO\",\"middle_name\":\"JOHN\",\"last_name\":\"OLUWASEUN\",\"full_name\":\"ADEBAYO JOHN OLUWASEUN\",\"email\":\"adebayo@example.com\",\"gender\":\"Male\",\"phone_number\":\"08031234567\",\"phone_number_2\":null,\"date_of_birth\":\"12-Apr-1990\",\"formatted_date_of_birth\":\"1990-04-12\",\"lga_of_origin\":\"Ikeja\",\"state_of_origin\":\"Lagos State\",\"nationality\":null,\"marital_status\":\"Single\",\"image_url\":\"https:\\/\\/images.example.com\\/bvn\\/22212345678.jpg\"},\"residential_info\":{\"state_of_residence\":\"Lagos State\",\"lga_of_residence\":null,\"residential_address\":\"12 Allen Avenue, Ikeja\"}}",
                                                "id": 3051,
                                                "bvn": "22212345678",
                                                "bvn_image": "_BVN/22212345678.jpg",
                                                "created_at": "2026-11-21 12:01:33"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "417": {
                        "description": "Rejected",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "not_onboarded": {
                                        "summary": "Your business is not enabled for this product",
                                        "value": {
                                            "status": "failed",
                                            "message": "you are not onboarded for this service... contact support",
                                            "data": null
                                        }
                                    },
                                    "duplicate": {
                                        "summary": "The tranx_id was already used",
                                        "value": {
                                            "status": "failed",
                                            "message": "duplicate transaction detected....",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    },
                                    "not_found": {
                                        "summary": "BVN not found",
                                        "value": {
                                            "status": "failed",
                                            "message": "BVN record not found. please contact support or try again.",
                                            "data": null
                                        }
                                    },
                                    "no_match": {
                                        "summary": "Names do not match",
                                        "value": {
                                            "status": "failed",
                                            "message": "unable to verify BVN with your account name",
                                            "data": []
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/kyc/validate_bvn": {
            "post": {
                "tags": [
                    "KYC"
                ],
                "summary": "Validate BVN",
                "operationId": "validateBvn",
                "description": "Validates a BVN against a first and last name and returns the personal information on a match. Each call is charged.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "bvn",
                                    "firstname",
                                    "lastname",
                                    "tranx_id"
                                ],
                                "properties": {
                                    "bvn": {
                                        "type": "string",
                                        "description": "11-digit Bank Verification Number.",
                                        "minLength": 10,
                                        "example": "22212345678"
                                    },
                                    "firstname": {
                                        "type": "string",
                                        "description": "First name to match against the BVN record.",
                                        "example": "Adebayo"
                                    },
                                    "lastname": {
                                        "type": "string",
                                        "description": "Last name to match against the BVN record.",
                                        "example": "Oluwaseun"
                                    },
                                    "tranx_id": {
                                        "type": "string",
                                        "description": "Your unique reference for this request, at least 10 characters. A reference can only be used once; reusing it returns \"duplicate transaction detected\". Store it so you can verify the transaction later.",
                                        "minLength": 10,
                                        "example": "ACME-20261121-000184"
                                    }
                                }
                            },
                            "example": {
                                "bvn": "22212345678",
                                "firstname": "Adebayo",
                                "lastname": "Oluwaseun",
                                "tranx_id": "ACME-KYC-0000000101"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Valid",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "match": {
                                        "summary": "Match",
                                        "value": {
                                            "status": "success",
                                            "message": "name matching was successful",
                                            "data": {
                                                "first_name": "ADEBAYO",
                                                "middle_name": "JOHN",
                                                "last_name": "OLUWASEUN",
                                                "full_name": "ADEBAYO JOHN OLUWASEUN",
                                                "email": "adebayo@example.com",
                                                "gender": "Male",
                                                "phone_number": "08031234567",
                                                "phone_number_2": null,
                                                "date_of_birth": "12-Apr-1990",
                                                "formatted_date_of_birth": "1990-04-12",
                                                "lga_of_origin": "Ikeja",
                                                "state_of_origin": "Lagos State",
                                                "nationality": null,
                                                "marital_status": "Single"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "417": {
                        "description": "Rejected",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "not_onboarded": {
                                        "summary": "Your business is not enabled for this product",
                                        "value": {
                                            "status": "failed",
                                            "message": "you are not onboarded for this service... contact support",
                                            "data": null
                                        }
                                    },
                                    "duplicate": {
                                        "summary": "The tranx_id was already used",
                                        "value": {
                                            "status": "failed",
                                            "message": "duplicate transaction detected....",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    },
                                    "not_found": {
                                        "summary": "BVN not found",
                                        "value": {
                                            "status": "failed",
                                            "message": "BVN record not found. please contact support or try again.",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/kyc/verify_bvn_compare": {
            "post": {
                "tags": [
                    "KYC"
                ],
                "summary": "Compare BVN selfie",
                "operationId": "compareBvnSelfie",
                "description": "Compares a customer selfie with the BVN photo. `facial_data` lists face matches with a `Similarity` score from 0 to 100; an empty list means no match. Pick your own threshold (90+ is a common choice). Each call is charged.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "bvn",
                                    "firstname",
                                    "lastname",
                                    "client_image",
                                    "tranx_id"
                                ],
                                "properties": {
                                    "bvn": {
                                        "type": "string",
                                        "description": "11-digit Bank Verification Number.",
                                        "minLength": 10,
                                        "example": "22212345678"
                                    },
                                    "firstname": {
                                        "type": "string",
                                        "description": "First name to match against the BVN record.",
                                        "example": "Adebayo"
                                    },
                                    "lastname": {
                                        "type": "string",
                                        "description": "Last name to match against the BVN record.",
                                        "example": "Oluwaseun"
                                    },
                                    "client_image": {
                                        "type": "string",
                                        "description": "File name of the selfie already stored in SendCheap storage (`_USER_IMAGE` folder). Not a base64 image. Contact support to get selfie upload set up for your account.",
                                        "minLength": 10,
                                        "example": "selfie_7f3a9c21.jpg"
                                    },
                                    "tranx_id": {
                                        "type": "string",
                                        "description": "Your unique reference for this request, at least 10 characters. A reference can only be used once; reusing it returns \"duplicate transaction detected\". Store it so you can verify the transaction later.",
                                        "minLength": 10,
                                        "example": "ACME-20261121-000184"
                                    }
                                }
                            },
                            "example": {
                                "bvn": "22212345678",
                                "firstname": "Adebayo",
                                "lastname": "Oluwaseun",
                                "client_image": "selfie_7f3a9c21.jpg",
                                "tranx_id": "ACME-KYC-0000000101"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Processed",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "processed": {
                                        "summary": "Face match result",
                                        "value": {
                                            "status": "success",
                                            "message": "BVN processed successfully",
                                            "data": {
                                                "bvn_data": {
                                                    "id": 3051,
                                                    "bvn": "22212345678",
                                                    "bvn_data": {
                                                        "request_reference": "a1b2c3d4e5",
                                                        "infoId": 48211,
                                                        "bvn_number": "22212345678",
                                                        "name_on_card": "ADEBAYO OLUWASEUN",
                                                        "enrolment_branch": "IKEJA",
                                                        "enrolment_bank": "058",
                                                        "formatted_registration_date": "2014-06-03",
                                                        "level_of_account": "Level 2 - Medium Level Accounts",
                                                        "nin": null,
                                                        "watchlisted": "NO",
                                                        "verification_status": "VERIFIED",
                                                        "service_type": "BVN Full Details",
                                                        "personal_info": {
                                                            "first_name": "ADEBAYO",
                                                            "middle_name": "JOHN",
                                                            "last_name": "OLUWASEUN",
                                                            "full_name": "ADEBAYO JOHN OLUWASEUN",
                                                            "email": "adebayo@example.com",
                                                            "gender": "Male",
                                                            "phone_number": "08031234567",
                                                            "phone_number_2": null,
                                                            "date_of_birth": "12-Apr-1990",
                                                            "formatted_date_of_birth": "1990-04-12",
                                                            "lga_of_origin": "Ikeja",
                                                            "state_of_origin": "Lagos State",
                                                            "nationality": null,
                                                            "marital_status": "Single",
                                                            "image_url": "https://images.example.com/bvn/22212345678.jpg"
                                                        },
                                                        "residential_info": {
                                                            "state_of_residence": "Lagos State",
                                                            "lga_of_residence": null,
                                                            "residential_address": "12 Allen Avenue, Ikeja"
                                                        }
                                                    },
                                                    "bvn_image": "_BVN/22212345678.jpg",
                                                    "created_at": "2026-11-21 12:01:33"
                                                },
                                                "facial_data": [
                                                    {
                                                        "Similarity": 97.81000000000000227373675443232059478759765625,
                                                        "Face": {
                                                            "Confidence": 99.9899999999999948840923025272786617279052734375,
                                                            "BoundingBox": {
                                                                "Width": 0.419999999999999984456877655247808434069156646728515625,
                                                                "Height": 0.5500000000000000444089209850062616169452667236328125,
                                                                "Left": 0.289999999999999980015985556747182272374629974365234375,
                                                                "Top": 0.179999999999999993338661852249060757458209991455078125
                                                            }
                                                        }
                                                    }
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "417": {
                        "description": "Rejected",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "not_onboarded": {
                                        "summary": "Your business is not enabled for this product",
                                        "value": {
                                            "status": "failed",
                                            "message": "you are not onboarded for this service... contact support",
                                            "data": null
                                        }
                                    },
                                    "duplicate": {
                                        "summary": "The tranx_id was already used",
                                        "value": {
                                            "status": "failed",
                                            "message": "duplicate transaction detected....",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "missing": {
                                        "summary": "A required field was not sent",
                                        "value": {
                                            "status": "failed",
                                            "message": "bad request (tranx_id) not found in request param",
                                            "data": null
                                        }
                                    },
                                    "not_found": {
                                        "summary": "BVN not found",
                                        "value": {
                                            "status": "failed",
                                            "message": "BVN record not found. please contact support or try again.",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "406": {
                        "description": "Missing or invalid API token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "examples": {
                                    "unauthorized": {
                                        "summary": "Token missing, revoked or regenerated",
                                        "value": {
                                            "status": "failed",
                                            "message": "Unauthorized",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "Your API token from the SendCheap business dashboard."
            }
        },
        "schemas": {
            "Envelope": {
                "type": "object",
                "required": [
                    "status",
                    "message",
                    "data"
                ],
                "properties": {
                    "status": {
                        "type": "string",
                        "enum": [
                            "success",
                            "failed"
                        ],
                        "description": "`success` when the request did what you asked."
                    },
                    "message": {
                        "type": "string",
                        "description": "Human-readable result."
                    },
                    "data": {
                        "description": "The result. Shape depends on the endpoint; `null` on most errors."
                    }
                }
            }
        }
    }
}
