{
  "openapi": "3.1.0",
  "info": {
    "title": "Whish Pay Split",
    "version": "1.0.0",
    "description": "Collect a payment and record how it should be split across destination accounts, by amount or by percentage. The request and response contract is final; redistribution of funds to each breakdown identifier is still being finalized, so until it ships the breakdown is captured and held against the payment and the full amount is collected as normal."
  },
  "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": {
      "channelAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "channel"
      },
      "secretAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "secret"
      },
      "websiteUrlAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "websiteUrl"
      }
    }
  },
  "security": [
    {
      "channelAuth": [],
      "secretAuth": [],
      "websiteUrlAuth": []
    }
  ],
  "paths": {
    "/payment/account/balance": {
      "get": {
        "summary": "Get account balance",
        "responses": {
          "200": {
            "description": "Standard response envelope.",
            "content": {
              "application/json": {
                "example": {
                  "status": true,
                  "code": null,
                  "dialog": null,
                  "actions": null,
                  "extra": null,
                  "data": {
                    "balance": 10439.0
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "User-Agent",
            "in": "header",
            "required": true,
            "description": "Identifies your application. Format: `AppName/version (website; contact-email)`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "currency",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/payment/whish/split": {
      "post": {
        "summary": "Create a split payment",
        "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. `breakdown` maps any identifier you choose to a value. With `breakdownType` `amount` (the default) the values are literal amounts and should sum to `amount`; with `percentage` they are percentages of the payment and should sum to 100. `amount` is a number here, though a double-quoted string is also accepted. `successCallbackUrl`, `failureCallbackUrl`, `successRedirectUrl` and `failureRedirectUrl` are all required, and must be publicly reachable: a localhost or other non-public host is rejected with HTTP 403. Do not send `target`, `byWhish`, `installment` or `source`.",
        "responses": {
          "200": {
            "description": "Standard response envelope.",
            "content": {
              "application/json": {
                "example": {
                  "status": true,
                  "code": null,
                  "data": {
                    "collectUrl": "https://pay.whish.money/invoice/pay/?q=abc123"
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "User-Agent",
            "in": "header",
            "required": true,
            "description": "Identifies your application. Format: `AppName/version (website; contact-email)`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "example": {
                "amount": 100,
                "currency": "USD",
                "externalId": "your-unique-id-001",
                "invoice": "Order #1",
                "successCallbackUrl": "https://merchant.example/api/payment/success",
                "failureCallbackUrl": "https://merchant.example/api/payment/failure",
                "successRedirectUrl": "https://merchant.example/thank-you",
                "failureRedirectUrl": "https://merchant.example/payment-error",
                "breakdownType": "amount",
                "breakdown": {
                  "destination-1": 60,
                  "destination-2": 40
                }
              }
            }
          }
        }
      }
    },
    "/payment/collect/status": {
      "post": {
        "summary": "Get payment status",
        "responses": {
          "200": {
            "description": "Standard response envelope.",
            "content": {
              "application/json": {
                "example": {
                  "status": true,
                  "code": null,
                  "dialog": null,
                  "extra": null,
                  "data": {
                    "collectStatus": "success",
                    "payerPhoneNumber": "96170123456"
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "User-Agent",
            "in": "header",
            "required": true,
            "description": "Identifies your application. Format: `AppName/version (website; contact-email)`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "example": {
                "currency": "USD",
                "externalId": "your-unique-id-001"
              }
            }
          }
        }
      }
    }
  }
}