{
  "openapi": "3.1.0",
  "info": {
    "title": "KalphaPay API",
    "version": "1.3.0",
    "description": "Server-to-server API for creating cashier sessions, reading Pay Ins and requesting Pay Outs, plus the signed webhooks KalphaPay sends. Integration guide: https://docs.kalphapay.com/"
  },
  "servers": [
    {
      "url": "https://api.kalphapay.com"
    }
  ],
  "security": [
    {
      "secretKey": []
    }
  ],
  "tags": [
    {
      "name": "Sessions"
    },
    {
      "name": "Pay Ins"
    },
    {
      "name": "Payment methods"
    },
    {
      "name": "Pay Outs",
      "description": "Withdrawals: refunds to the cards used for Pay Ins first (return to source), then bank transfer."
    }
  ],
  "paths": {
    "/v1/sessions": {
      "post": {
        "tags": [
          "Sessions"
        ],
        "operationId": "createSession",
        "summary": "Create a cashier session",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique per logical request (e.g. your order_id). Replays with the same body return the original response.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SessionCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Session created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionCreateResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/sessions/{id}": {
      "get": {
        "tags": [
          "Sessions"
        ],
        "operationId": "getSession",
        "summary": "Retrieve a session and its payment attempts",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "session",
                    "transactions"
                  ],
                  "properties": {
                    "session": {
                      "$ref": "#/components/schemas/Session"
                    },
                    "transactions": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Transaction"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/transactions": {
      "get": {
        "tags": [
          "Pay Ins"
        ],
        "operationId": "listTransactions",
        "summary": "List Pay Ins (optionally for one order)",
        "parameters": [
          {
            "name": "order_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Newest first",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Transaction"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/transactions/{id}": {
      "get": {
        "tags": [
          "Pay Ins"
        ],
        "operationId": "getTransaction",
        "summary": "Retrieve a Pay In by UUID or reference",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Pay In UUID or reference (KP-…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "transaction"
                  ],
                  "properties": {
                    "transaction": {
                      "$ref": "#/components/schemas/Transaction"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/transactions/{id}/sync": {
      "post": {
        "tags": [
          "Pay Ins"
        ],
        "operationId": "syncTransaction",
        "summary": "Refresh the status from the payment provider now",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "transaction",
                    "changed"
                  ],
                  "properties": {
                    "transaction": {
                      "$ref": "#/components/schemas/Transaction"
                    },
                    "changed": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/payment-methods": {
      "get": {
        "tags": [
          "Payment methods"
        ],
        "operationId": "listPaymentMethods",
        "summary": "Payment methods the cashier would offer",
        "parameters": [
          {
            "name": "currency",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 3,
              "maxLength": 3
            }
          },
          {
            "name": "country",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            },
            "description": "ISO 3166-1 alpha-2. Picks the broker's cashier page for that country."
          },
          {
            "name": "amount",
            "in": "query",
            "schema": {
              "type": "number",
              "exclusiveMinimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "livemode",
                    "data"
                  ],
                  "properties": {
                    "livemode": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PaymentMethod"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          }
        },
        "description": "Same list, order and names as the broker's cashier page for the country (the Default page when the country has none)."
      }
    },
    "/v1/payouts": {
      "post": {
        "tags": [
          "Pay Outs"
        ],
        "operationId": "createPayout",
        "summary": "Create a Pay Out (withdrawal)",
        "description": "The CRM must already have deducted the amount from the trading account. Return the funds only on payout.failed / payout.rejected / payout.cancelled.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique per withdrawal (e.g. the CRM withdrawal UUID). Replays with the same body return the original response.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PayoutCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Pay Out created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PayoutCreateResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "get": {
        "tags": [
          "Pay Outs"
        ],
        "operationId": "listPayouts",
        "summary": "List Pay Outs (optionally by order_id)",
        "parameters": [
          {
            "name": "order_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 200,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pay Outs, newest first",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Payout"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/payouts/bank-schema": {
      "get": {
        "tags": [
          "Pay Outs"
        ],
        "operationId": "getBankSchema",
        "summary": "Bank fields required for a bank Pay Out",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            }
          },
          {
            "name": "currency",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 3,
              "maxLength": 3
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Field schema",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankSchema"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/payouts/{id}": {
      "get": {
        "tags": [
          "Pay Outs"
        ],
        "operationId": "getPayout",
        "summary": "Retrieve a Pay Out",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Pay Out id or PO- reference",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pay Out",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "payout": {
                      "$ref": "#/components/schemas/Payout"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/payouts/{id}/cancel": {
      "post": {
        "tags": [
          "Pay Outs"
        ],
        "operationId": "cancelPayout",
        "summary": "Cancel a Pay Out before payment starts",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Pay Out id or PO- reference",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string",
                    "maxLength": 300
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cancelled",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "payout": {
                      "$ref": "#/components/schemas/Payout"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "webhooks": {
    "transactionEvent": {
      "post": {
        "summary": "Pay In reached a final status",
        "description": "Sent to the session notification_url (or the merchant webhook URL). Verify KalphaPay-Signature: t=<unix>,v1=hex(HMAC-SHA256(webhook_secret, t + '.' + raw_body)). Reply 2xx within 15 s; up to 8 attempts with backoff. Delivery is at-least-once: de-duplicate by event id, credit once per data.transaction.id.",
        "parameters": [
          {
            "name": "KalphaPay-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "t=1795305600,v1=5b2c0e…"
            }
          },
          {
            "name": "KalphaPay-Event-Id",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "KalphaPay-Event-Type",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEvent"
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Acknowledged"
          }
        }
      }
    },
    "payoutEvent": {
      "post": {
        "summary": "Pay Out status changed",
        "description": "Sent to the Pay Out notification_url (or the merchant webhook URL), signed like Pay In webhooks. Return funds to the trading account only on payout.failed, payout.rejected or payout.cancelled (once per data.payout.id).",
        "parameters": [
          {
            "name": "KalphaPay-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "t=1795305600,v1=5b2c0e…"
            }
          },
          {
            "name": "KalphaPay-Event-Id",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "KalphaPay-Event-Type",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PayoutWebhookEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "secretKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Merchant secret API key (sk_live_… or sk_test_…). A merchant can have several keys, e.g. one per CRM payment gateway; each opens the main cashier page or its own page, and /v1/payment-methods answers for the calling key's page."
      }
    },
    "responses": {
      "Error": {
        "description": "Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "SessionCreateRequest": {
        "type": "object",
        "required": [
          "order_id",
          "currency"
        ],
        "properties": {
          "order_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "^[^\"'/`<>{}+@\\s]+$",
            "description": "Your unique Pay In reference"
          },
          "amount": {
            "type": "number",
            "exclusiveMinimum": 0,
            "description": "Major units. Omit to let the client enter the amount."
          },
          "currency": {
            "type": "string",
            "minLength": 3,
            "maxLength": 3,
            "description": "ISO 4217"
          },
          "amount_locked": {
            "type": "boolean",
            "description": "Defaults to true when amount is sent"
          },
          "country": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2,
            "description": "ISO 3166-1 alpha-2 of the client. Picks the broker's cashier page for that country and the eligible methods. Defaults to customer.country."
          },
          "language": {
            "type": "string",
            "minLength": 2,
            "maxLength": 5
          },
          "theme": {
            "type": "string",
            "enum": [
              "light",
              "dark"
            ]
          },
          "customer": {
            "type": "object",
            "properties": {
              "email": {
                "type": "string",
                "format": "email"
              },
              "first_name": {
                "type": "string",
                "maxLength": 100
              },
              "last_name": {
                "type": "string",
                "maxLength": 100
              },
              "phone": {
                "type": "string",
                "maxLength": 30
              },
              "country": {
                "type": "string",
                "minLength": 2,
                "maxLength": 2
              }
            }
          },
          "trading_account": {
            "type": "object",
            "required": [
              "login"
            ],
            "description": "Informational. KalphaPay does not credit it; your CRM does.",
            "properties": {
              "login": {
                "type": "string",
                "maxLength": 64
              }
            }
          },
          "notification_url": {
            "type": "string",
            "format": "uri",
            "description": "HTTPS webhook target for this session"
          },
          "success_url": {
            "type": "string",
            "format": "uri"
          },
          "failure_url": {
            "type": "string",
            "format": "uri"
          },
          "cancel_url": {
            "type": "string",
            "format": "uri"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "payload": {
            "type": "string",
            "maxLength": 1000
          }
        }
      },
      "Session": {
        "type": "object",
        "required": [
          "id",
          "order_id",
          "currency",
          "amount_locked",
          "status",
          "expires_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "order_id": {
            "type": "string"
          },
          "amount": {
            "type": [
              "number",
              "null"
            ]
          },
          "currency": {
            "type": "string"
          },
          "amount_locked": {
            "type": "boolean"
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "completed",
              "expired"
            ]
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SessionCreateResponse": {
        "type": "object",
        "required": [
          "livemode",
          "session",
          "token",
          "cashier_url",
          "launcher"
        ],
        "properties": {
          "livemode": {
            "type": "boolean"
          },
          "session": {
            "$ref": "#/components/schemas/Session"
          },
          "token": {
            "type": "string",
            "description": "Session token for the cashier / launcher"
          },
          "cashier_url": {
            "type": "string",
            "format": "uri"
          },
          "launcher": {
            "type": "object",
            "properties": {
              "script_url": {
                "type": "string",
                "format": "uri"
              },
              "html": {
                "type": "string"
              }
            }
          }
        }
      },
      "Transaction": {
        "type": "object",
        "required": [
          "id",
          "reference",
          "type",
          "status",
          "order_id",
          "amount",
          "amount_minor",
          "currency",
          "attempt",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "reference": {
            "type": "string",
            "example": "KP-J52EZELAFT"
          },
          "type": {
            "type": "string",
            "enum": [
              "deposit"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "created",
              "pending",
              "approved",
              "declined",
              "failed",
              "cancelled",
              "expired"
            ]
          },
          "order_id": {
            "type": "string"
          },
          "amount": {
            "type": "number"
          },
          "amount_minor": {
            "type": "integer"
          },
          "currency": {
            "type": "string"
          },
          "customer": {
            "type": "object",
            "properties": {
              "email": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "first_name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "last_name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "country": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "payment": {
            "type": "object",
            "properties": {
              "provider": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "stripe",
                  "airwallex",
                  "simulator",
                  null
                ]
              },
              "psp_reference": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "method": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "card_brand": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "card_last4": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "decline_reason": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "trading_account": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "login": {
                "type": "string"
              }
            }
          },
          "credit": {
            "type": [
              "object",
              "null"
            ],
            "description": "Only when KalphaPay credits the account itself (CRM-API mode)",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "not_required",
                  "pending",
                  "processing",
                  "done",
                  "failed",
                  "needs_review"
                ]
              },
              "system_uuid": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "reference": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "attempt": {
            "type": "integer"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "completed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "source": {
            "type": "string",
            "enum": [
              "api",
              "portal",
              "payment_link"
            ],
            "description": "Webhooks only: where the payment started."
          },
          "payment_link_id": {
            "type": "string",
            "nullable": true,
            "description": "Webhooks only: set for payment-link payments."
          },
          "payout_id": {
            "type": "string",
            "nullable": true
          },
          "refunded_transaction_id": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "PaymentMethod": {
        "type": "object",
        "required": [
          "id",
          "title",
          "subtitle",
          "icons",
          "provider"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string",
            "description": "Name shown to the client (set per country in the cashier designer)."
          },
          "subtitle": {
            "type": [
              "string",
              "null"
            ],
            "description": "Second line under the name."
          },
          "icons": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Logos for the method: visa, mastercard, amex, jcb, unionpay, discover, applepay, googlepay, card, bank, qr, wallet, crypto, cash, or flag:XX (ISO country code)."
          },
          "provider": {
            "type": "string"
          },
          "min_amount": {
            "type": [
              "number",
              "null"
            ]
          },
          "max_amount": {
            "type": [
              "number",
              "null"
            ]
          }
        }
      },
      "WebhookEvent": {
        "type": "object",
        "required": [
          "id",
          "type",
          "created_at",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string",
            "example": "evt_6c1d8a9b2f3e4d5c8b7a6f5e4d3c2b1a"
          },
          "type": {
            "type": "string",
            "enum": [
              "transaction.approved",
              "transaction.declined",
              "transaction.failed",
              "transaction.cancelled",
              "transaction.expired",
              "transaction.credited",
              "test.ping"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object",
            "properties": {
              "transaction": {
                "$ref": "#/components/schemas/Transaction"
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string",
            "example": "validation_error"
          },
          "message": {
            "type": "string"
          },
          "details": {}
        }
      },
      "PayoutCreateRequest": {
        "type": "object",
        "required": [
          "order_id",
          "amount",
          "currency",
          "customer"
        ],
        "properties": {
          "order_id": {
            "type": "string",
            "maxLength": 255,
            "description": "Your withdrawal id, unique per merchant."
          },
          "amount": {
            "type": "number",
            "exclusiveMinimum": 0,
            "example": 1000
          },
          "currency": {
            "type": "string",
            "example": "USD"
          },
          "method": {
            "type": "string",
            "enum": [
              "auto",
              "card_refund",
              "bank_transfer"
            ],
            "default": "auto"
          },
          "customer": {
            "type": "object",
            "required": [
              "email"
            ],
            "properties": {
              "email": {
                "type": "string",
                "format": "email"
              },
              "first_name": {
                "type": "string"
              },
              "last_name": {
                "type": "string"
              },
              "country": {
                "type": "string"
              }
            }
          },
          "trading_account": {
            "type": "object",
            "properties": {
              "login": {
                "type": "string"
              }
            }
          },
          "bank_account": {
            "type": "object",
            "required": [
              "country",
              "fields"
            ],
            "properties": {
              "country": {
                "type": "string",
                "example": "GB"
              },
              "fields": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Keys from GET /v1/payouts/bank-schema."
              }
            }
          },
          "notification_url": {
            "type": "string",
            "format": "uri"
          },
          "return_url": {
            "type": "string",
            "format": "uri"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "payload": {
            "type": "string",
            "maxLength": 1000
          }
        }
      },
      "PayoutLeg": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "reference": {
            "type": "string"
          },
          "method": {
            "type": "string",
            "enum": [
              "card_refund",
              "bank_transfer"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "paid",
              "failed",
              "cancelled"
            ]
          },
          "amount": {
            "type": "number"
          },
          "provider": {
            "type": "string",
            "nullable": true
          },
          "psp_reference": {
            "type": "string",
            "nullable": true
          },
          "card": {
            "type": "object",
            "nullable": true,
            "properties": {
              "brand": {
                "type": "string",
                "nullable": true
              },
              "last4": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "refunded_transaction_id": {
            "type": "string",
            "nullable": true
          },
          "failure_reason": {
            "type": "string",
            "nullable": true
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Payout": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "reference": {
            "type": "string",
            "example": "PO-7F3K9Q2MXA"
          },
          "order_id": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "api",
              "back_office"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "awaiting_details",
              "pending_approval",
              "approved",
              "processing",
              "needs_review",
              "completed",
              "failed",
              "rejected",
              "cancelled"
            ]
          },
          "amount": {
            "type": "number"
          },
          "amount_minor": {
            "type": "integer"
          },
          "paid_amount": {
            "type": "number"
          },
          "currency": {
            "type": "string"
          },
          "method": {
            "type": "string",
            "enum": [
              "auto",
              "card_refund",
              "bank_transfer"
            ]
          },
          "customer": {
            "type": "object",
            "properties": {
              "email": {
                "type": "string"
              },
              "first_name": {
                "type": "string",
                "nullable": true
              },
              "last_name": {
                "type": "string",
                "nullable": true
              },
              "country": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "trading_account": {
            "type": "object",
            "nullable": true,
            "properties": {
              "login": {
                "type": "string"
              }
            }
          },
          "requires_approval": {
            "type": "boolean"
          },
          "bank_account": {
            "type": "object",
            "nullable": true,
            "properties": {
              "country": {
                "type": "string"
              },
              "currency": {
                "type": "string"
              },
              "transfer_method": {
                "type": "string",
                "enum": [
                  "LOCAL",
                  "SWIFT"
                ]
              },
              "account_hint": {
                "type": "string",
                "example": "•••• 5678"
              }
            }
          },
          "plan": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "method": {
                  "type": "string"
                },
                "amount": {
                  "type": "number"
                },
                "refunded_transaction": {
                  "type": "string",
                  "nullable": true
                },
                "card": {
                  "type": "object",
                  "nullable": true
                }
              }
            }
          },
          "legs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PayoutLeg"
            }
          },
          "failure_reason": {
            "type": "string",
            "nullable": true
          },
          "rejection_reason": {
            "type": "string",
            "nullable": true
          },
          "metadata": {
            "type": "object"
          },
          "payload": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "completed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "PayoutCreateResponse": {
        "type": "object",
        "properties": {
          "livemode": {
            "type": "boolean"
          },
          "payout": {
            "$ref": "#/components/schemas/Payout"
          },
          "details_url": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "Hosted bank-details page when a bank transfer is needed and no bank_account was sent."
          }
        }
      },
      "BankSchema": {
        "type": "object",
        "properties": {
          "country": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "transfer_method": {
            "type": "string",
            "enum": [
              "LOCAL",
              "SWIFT"
            ]
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "required": {
                  "type": "boolean"
                },
                "pattern": {
                  "type": "string",
                  "nullable": true
                },
                "options": {
                  "type": "array",
                  "nullable": true,
                  "items": {
                    "type": "object",
                    "properties": {
                      "value": {
                        "type": "string"
                      },
                      "label": {
                        "type": "string"
                      }
                    }
                  }
                },
                "default": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          }
        }
      },
      "PayoutWebhookEvent": {
        "type": "object",
        "required": [
          "id",
          "type",
          "created_at",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "payout.processing",
              "payout.completed",
              "payout.failed",
              "payout.rejected",
              "payout.cancelled"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object",
            "properties": {
              "payout": {
                "$ref": "#/components/schemas/Payout"
              }
            }
          }
        }
      }
    }
  }
}
