{
  "openapi": "3.1.0",
  "info": {
    "title": "Blaaiz Platform API - Fees Breakdown",
    "version": "1.0.0",
    "description": "Calculate fees for a transaction before initiating it"
  },
  "tags": [
    {
      "name": "Fees"
    }
  ],
  "servers": [
    {
      "url": "https://api-prod.blaaiz.com"
    },
    {
      "url": "https://api-dev.blaaiz.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "oauth2ClientCredentials": {
        "type": "oauth2",
        "description": "Use your OAuth client credentials to obtain a short-lived Bearer token from POST /oauth/token.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "/oauth/token",
            "scopes": {
              "fees:read": "Read fee breakdowns."
            }
          }
        }
      }
    },
    "schemas": {
      "FeeBreakdownRequest": {
        "type": "object",
        "description": "This retrieves a detailed fee breakdown for a specific transaction type between two currencies. By providing the necessary parameters, businesses can understand the applicable fees for sending or receiving funds, whether through bank transfers or other methods. This endpoint supports transactions in various currencies, allowing for flexibility and transparency in financial operations.",
        "properties": {
          "from_currency_id": {
            "type": "string",
            "description": "Currency code you are sending from (e.g., NGN, CAD, USD)"
          },
          "to_currency_id": {
            "type": "string",
            "description": "Currency code the recipient will receive (e.g., NGN, CAD, USD)"
          },
          "from_amount": {
            "type": "number",
            "description": "Amount to deduct from your wallet"
          },
          "to_amount": {
            "type": "number",
            "description": "Exact amount the recipient should receive"
          }
        },
        "required": [
          "from_currency_id",
          "to_currency_id",
          "from_amount"
        ]
      },
      "FeeItem": {
        "type": "object",
        "properties": {
          "method": {
            "type": "string",
            "description": "Method this fee applies to (e.g., card, ach, bank_transfer, interac)"
          },
          "amount": {
            "type": "number",
            "description": "Fee amount"
          },
          "fee": {
            "type": "number",
            "description": "Alias for amount, as returned by the controller"
          },
          "you_send": {
            "type": "number"
          },
          "total_amount_to_send": {
            "type": "number"
          },
          "recipient_gets": {
            "type": "number"
          },
          "our_fee": {
            "type": "number"
          },
          "total_fees": {
            "type": "number"
          },
          "amountIsRecipientGets": {
            "type": "boolean"
          },
          "amountIsYouSend": {
            "type": "boolean"
          },
          "rate": {
            "type": "number"
          }
        },
        "required": [
          "method",
          "amount"
        ]
      },
      "FeeBreakdownResponse": {
        "type": "object",
        "properties": {
          "our_fee": {
            "type": "number",
            "description": "Total fee charged by Blaaiz for this breakdown."
          },
          "collection_fees": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FeeItem"
            }
          },
          "payout_fees": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FeeItem"
            }
          }
        },
        "required": [
          "our_fee",
          "collection_fees",
          "payout_fees"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        },
        "required": [
          "message"
        ]
      }
    }
  },
  "paths": {
    "/api/external/fees/breakdown": {
      "post": {
        "summary": "Get fees breakdown",
        "description": "Calculate fees for a transaction between two currencies. Provide either from_amount or to_amount (not both). Required scope: `fees:read`.",
        "tags": [
          "Fees"
        ],
        "security": [
          {
            "oauth2ClientCredentials": [
              "fees:read"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FeeBreakdownRequest"
              },
              "example": {
                "from_currency_id": "NGN",
                "to_currency_id": "NGN",
                "from_amount": 50000
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Fee breakdown calculated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeeBreakdownResponse"
                },
                "example": {
                  "our_fee": 1.5,
                  "collection_fees": [
                    {
                      "method": "CARD",
                      "amount": 2,
                      "fee": 2,
                      "you_send": 100,
                      "total_amount_to_send": 96.5,
                      "recipient_gets": 58000,
                      "our_fee": 1.5,
                      "total_fees": 3.5,
                      "amountIsRecipientGets": false,
                      "amountIsYouSend": true,
                      "rate": 600.5
                    },
                    {
                      "method": "OPEN_BANKING",
                      "amount": 0.5,
                      "fee": 0.5,
                      "you_send": 100,
                      "total_amount_to_send": 98,
                      "recipient_gets": 58900,
                      "our_fee": 1.5,
                      "total_fees": 2,
                      "amountIsRecipientGets": false,
                      "amountIsYouSend": true,
                      "rate": 600.5
                    }
                  ],
                  "payout_fees": [
                    {
                      "method": "BANK_TRANSFER",
                      "amount": 0,
                      "fee": 0,
                      "you_send": 100,
                      "total_amount_to_send": 98.5,
                      "recipient_gets": 59200,
                      "our_fee": 1.5,
                      "total_fees": 1.5,
                      "amountIsRecipientGets": false,
                      "amountIsYouSend": true,
                      "rate": 600.5
                    },
                    {
                      "method": "MOBILE_MONEY",
                      "amount": 1,
                      "fee": 1,
                      "you_send": 100,
                      "total_amount_to_send": 97.5,
                      "recipient_gets": 58600,
                      "our_fee": 1.5,
                      "total_fees": 2.5,
                      "amountIsRecipientGets": false,
                      "amountIsYouSend": true,
                      "rate": 600.5
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": false,
                  "message": "Invalid request parameters"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": false,
                  "message": "Invalid or missing access token"
                }
              }
            }
          }
        }
      }
    }
  }
}