{
  "openapi": "3.1.0",
  "info": {
    "title": "Whish International Topup",
    "version": "1.0.0",
    "description": "Fetch a provider's top-up options for a customer target, then pay for the selected option. {provider} is the provider code Whish gives you (for example etisalatNba)."
  },
  "servers": [
    {
      "url": "https://partner.api.sbx.whish.money/itel-service/api",
      "description": "Sandbox"
    },
    {
      "url": "https://api.whish.money/itel-service/api",
      "description": "Production"
    }
  ],
  "components": {
    "securitySchemes": {
      "sessionIdAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "sessionId"
      },
      "tokenAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "token"
      }
    }
  },
  "security": [
    {
      "sessionIdAuth": [],
      "tokenAuth": []
    }
  ],
  "paths": {
    "/account/balance": {
      "get": {
        "summary": "Get account balance",
        "responses": {
          "200": {
            "description": "Standard response envelope.",
            "content": {
              "application/json": {
                "example": {
                  "status": true,
                  "code": null,
                  "dialog": null,
                  "extra": null,
                  "data": {
                    "balanceDetails": {
                      "balance": 940.0,
                      "voidBalance": 0.0
                    }
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "User-Agent",
            "in": "header",
            "required": true,
            "description": "Identifies your application. Format: `AppName/version (website; contact-email)`.",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/v2/{provider}/fetch": {
      "post": {
        "summary": "List top-up options",
        "responses": {
          "200": {
            "description": "Standard response envelope.",
            "content": {
              "application/json": {
                "example": {
                  "status": true,
                  "code": null,
                  "dialog": null,
                  "actions": null,
                  "extra": null,
                  "retrieved": true,
                  "data": {
                    "target": "+971561234567",
                    "options": [
                      {
                        "id": "341504052",
                        "displayName": "100 local mints for 30 days. AED 10",
                        "amount": 10.0,
                        "price": 10.0,
                        "currency": "AED",
                        "metadata": {}
                      },
                      {
                        "id": "341504048",
                        "displayName": "1GB local daily for 30 days and free Burger king meal. AED45",
                        "amount": 44.99,
                        "price": 44.99,
                        "currency": "AED",
                        "metadata": {}
                      },
                      {
                        "id": "341504049",
                        "displayName": "30 Intl mint daily Ind.Pak.Ban.Egy.Afg. Month AED 30",
                        "amount": 30.0,
                        "price": 30.0,
                        "currency": "AED",
                        "metadata": {}
                      },
                      {
                        "id": "341504051",
                        "displayName": "500 MB daily and 200 Int mints to IND BANG PAK AFG EGP for 30 days. AED35",
                        "amount": 35.0,
                        "price": 35.0,
                        "currency": "AED",
                        "metadata": {}
                      },
                      {
                        "id": "341504050",
                        "displayName": "500MB daily and 100 Local mints for 30 days. AED35",
                        "amount": 35.0,
                        "price": 35.0,
                        "currency": "AED",
                        "metadata": {}
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "User-Agent",
            "in": "header",
            "required": true,
            "description": "Identifies your application. Format: `AppName/version (website; contact-email)`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "example": {
                "target": "+971561234567"
              }
            }
          }
        }
      }
    },
    "/v2/{provider}/pay": {
      "post": {
        "summary": "Pay for a top-up",
        "description": "The `externalId` must be UNIQUE for every new transaction. It is a String, and it is the idempotency key: re-sending a value that was already used does NOT create a second transaction, it replays the original result. Only reuse the same `externalId` when you are deliberately retrying the very same transaction (for example after a timeout), and mint a new one for every genuinely new transaction. Send the selected option's amount exactly as List top-up options returned it.",
        "responses": {
          "200": {
            "description": "Standard response envelope.",
            "content": {
              "application/json": {
                "example": {
                  "status": true,
                  "code": null,
                  "dialog": {
                    "title": "Success",
                    "message": "You have successfully paid the bill for +971561234567",
                    "yesButton": null,
                    "noButton": null
                  },
                  "actions": null,
                  "extra": null,
                  "data": {
                    "listOfSoldItems": [
                      {
                        "transactionId": "20263096",
                        "service": "ETISALAT BUNDLES",
                        "picture": "",
                        "pictureUrl": "",
                        "denomination": "Etisalat NBA",
                        "serial": null,
                        "secret": null,
                        "formattedSecret": null,
                        "phone": "+971561234567",
                        "amount": "10 USD",
                        "originalAmount": "10 USD",
                        "fees": null,
                        "validity": null,
                        "expiry": "2026-07-17",
                        "help": "For assistance, please contact +971 52 108 8999",
                        "time": "13:07",
                        "date": "2026-07-17",
                        "voided": false,
                        "fromVoid": false,
                        "printType": 2,
                        "viewType": 2
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "User-Agent",
            "in": "header",
            "required": true,
            "description": "Identifies your application. Format: `AppName/version (website; contact-email)`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "example": {
                "target": "+971561234567",
                "optionId": "341504052",
                "amount": 10.0,
                "externalId": "681958946"
              }
            }
          }
        }
      }
    }
  }
}