{
  "openapi": "3.0.3",
  "info": {
    "title": "RapidBills Reseller API",
    "version": "1.0.0",
    "description": "Use the RapidBills reseller API to fetch product catalogs and pricing, check wallet balance, and purchase airtime, data, electricity, cable, exam pins, and gift cards.",
    "contact": {
      "name": "RapidBills Support",
      "email": "info@rapidbills.ng",
      "url": "https://www.rapidbills.ng/contact/"
    }
  },
  "servers": [
    {
      "url": "https://www.rapidbills.ng/api/reseller/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "BearerApiKey": []
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Send `Authorization: Bearer YOUR_API_KEY`."
      },
      "HeaderApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "schemas": {
      "WalletChoice": {
        "type": "string",
        "enum": [
          "main",
          "balance",
          "cashback"
        ],
        "default": "main"
      },
      "ApiResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "true",
              "false"
            ]
          },
          "message": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "description": "A unique key for one logical purchase or key-rotation action.",
        "schema": {
          "type": "string",
          "maxLength": 128
        }
      }
    }
  },
  "paths": {
    "/profile/": {
      "get": {
        "summary": "Get API reseller profile",
        "responses": {
          "200": {
            "description": "Profile fetched successfully."
          }
        }
      }
    },
    "/reset-key/": {
      "post": {
        "summary": "Rotate API key",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "API key rotated successfully."
          }
        }
      }
    },
    "/catalog/": {
      "get": {
        "summary": "Get providers and product catalog",
        "responses": {
          "200": {
            "description": "Catalog fetched successfully."
          }
        }
      }
    },
    "/pricing/": {
      "get": {
        "summary": "Get tier pricing",
        "responses": {
          "200": {
            "description": "Tier pricing fetched successfully."
          }
        }
      }
    },
    "/user-balance/": {
      "get": {
        "summary": "Get reseller wallet balance",
        "responses": {
          "200": {
            "description": "Balance fetched successfully."
          }
        }
      }
    },
    "/buy-airtime/": {
      "post": {
        "summary": "Buy airtime",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "provider_id",
                  "amount",
                  "number"
                ],
                "properties": {
                  "provider_id": {
                    "type": "integer"
                  },
                  "amount": {
                    "type": "integer"
                  },
                  "number": {
                    "type": "string"
                  },
                  "wallet": {
                    "$ref": "#/components/schemas/WalletChoice"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Airtime purchase successful."
          }
        }
      }
    },
    "/buy-data/": {
      "post": {
        "summary": "Buy data bundle",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "bundle_id",
                  "number"
                ],
                "properties": {
                  "bundle_id": {
                    "type": "integer"
                  },
                  "number": {
                    "type": "string"
                  },
                  "wallet": {
                    "$ref": "#/components/schemas/WalletChoice"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Data purchase successful."
          }
        }
      }
    },
    "/buy-power/": {
      "post": {
        "summary": "Pay electricity bill",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "provider_id",
                  "amount",
                  "meter_type",
                  "meter_number"
                ],
                "properties": {
                  "provider_id": {
                    "type": "integer"
                  },
                  "amount": {
                    "type": "integer"
                  },
                  "meter_type": {
                    "type": "integer",
                    "enum": [
                      1,
                      2
                    ]
                  },
                  "meter_number": {
                    "type": "string"
                  },
                  "phone_number": {
                    "type": "string"
                  },
                  "wallet": {
                    "$ref": "#/components/schemas/WalletChoice"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Electricity purchase successful."
          }
        }
      }
    },
    "/buy-cable/": {
      "post": {
        "summary": "Buy cable or streaming plan",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "plan_id",
                  "card_number"
                ],
                "properties": {
                  "plan_id": {
                    "type": "integer"
                  },
                  "card_number": {
                    "type": "string"
                  },
                  "wallet": {
                    "$ref": "#/components/schemas/WalletChoice"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cable purchase successful."
          }
        }
      }
    },
    "/buy-exam/": {
      "post": {
        "summary": "Buy exam result checker pin",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "exam_id"
                ],
                "properties": {
                  "exam_id": {
                    "type": "integer"
                  },
                  "wallet": {
                    "$ref": "#/components/schemas/WalletChoice"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Exam purchase successful."
          }
        }
      }
    },
    "/buy-gift-card/": {
      "post": {
        "summary": "Buy RapidBills gift card",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "amount"
                ],
                "properties": {
                  "amount": {
                    "type": "number",
                    "minimum": 500,
                    "maximum": 10000
                  },
                  "wallet": {
                    "$ref": "#/components/schemas/WalletChoice"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Gift card purchase successful."
          }
        }
      }
    },
    "/redeem-gift-card/": {
      "post": {
        "summary": "Redeem RapidBills gift card",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "code"
                ],
                "properties": {
                  "code": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Gift card redeemed successfully."
          }
        }
      }
    }
  }
}