{
  "openapi": "3.1.0",
  "info": {
    "title": "NbtaPay API",
    "version": "1.0.0",
    "description": "Server-to-server REST API for NbtaPay merchants. Authenticate with an organization API key as a Bearer token. All amounts are USDT strings."
  },
  "servers": [
    {
      "url": "https://api.nbta.sbarah.com/v1",
      "description": "NbtaPay API v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Account"
    },
    {
      "name": "Products"
    },
    {
      "name": "Checkouts"
    },
    {
      "name": "Payments"
    },
    {
      "name": "Balances"
    }
  ],
  "paths": {
    "/account": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Get account info",
        "description": "Returns the calling organization. Scope: account:read.",
        "responses": {
          "200": {
            "description": "Account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "name": {
                      "type": "string"
                    },
                    "slug": {
                      "type": "string"
                    },
                    "tier": {
                      "type": "string"
                    },
                    "environment": {
                      "type": "string",
                      "enum": [
                        "live",
                        "test"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the account:read scope",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/products": {
      "get": {
        "tags": [
          "Products"
        ],
        "summary": "List products",
        "description": "Lists the organization products. Scope: products:read.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "created_at of the last item from the previous page.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of products",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Product"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the products:read scope",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/products/{id}": {
      "get": {
        "tags": [
          "Products"
        ],
        "summary": "Get a product",
        "description": "Scope: products:read.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Product",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the products:read scope",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No product with that id in your organization",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/checkouts": {
      "post": {
        "tags": [
          "Checkouts"
        ],
        "summary": "Create a checkout",
        "description": "Creates a hosted checkout (invoice) for one of your products and returns a URL to send the buyer to. Scope: payments:write. Send an Idempotency-Key header to make retries safe.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CheckoutRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Checkout created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "invoice_id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "example": "pending"
                    },
                    "checkout_url": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the payments:write scope",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No product with that id in your organization",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Invalid body or Idempotency-Key reuse with a different body",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/payments": {
      "get": {
        "tags": [
          "Payments"
        ],
        "summary": "List payments",
        "description": "Cursor-paginated by created_at descending. Scope: payments:read.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "confirming",
                "confirmed",
                "expired",
                "refund_initiated"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of payments",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Payment"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the payments:read scope",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/payments/{invoiceId}": {
      "get": {
        "tags": [
          "Payments"
        ],
        "summary": "Get a payment",
        "description": "Scope: payments:read.",
        "parameters": [
          {
            "name": "invoiceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Payment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Payment"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the payments:read scope",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No payment with that invoice id in your organization",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/balances": {
      "get": {
        "tags": [
          "Balances"
        ],
        "summary": "Get balances",
        "description": "On-chain settlement totals for the organization. Merchants are paid directly on-chain (non-custodial), so by_chain is informational. Scope: balances:read.",
        "responses": {
          "200": {
            "description": "Balances",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Balances"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the balances:read scope",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "An organization API key, e.g. nbta_sk_live_xxx, sent as a Bearer token."
      }
    },
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 7807 problem document.",
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "instance": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          }
        },
        "required": [
          "title",
          "status"
        ]
      },
      "Product": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "price_usdt": {
            "type": "string",
            "example": "2"
          },
          "status": {
            "type": "string",
            "example": "active"
          },
          "accepted_chains": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "bsc",
                "polygon"
              ]
            }
          },
          "sales_count": {
            "type": "integer"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Payment": {
        "type": "object",
        "properties": {
          "invoice_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "confirming",
              "confirmed",
              "expired",
              "refund_initiated"
            ]
          },
          "amount_usdt": {
            "type": "string",
            "example": "2"
          },
          "chain": {
            "type": "string",
            "enum": [
              "bsc",
              "polygon",
              "unknown"
            ]
          },
          "chain_id": {
            "type": "integer",
            "example": 56
          },
          "product_id": {
            "type": "string",
            "format": "uuid"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "confirmed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "CheckoutRequest": {
        "type": "object",
        "required": [
          "product_id",
          "chain"
        ],
        "properties": {
          "product_id": {
            "type": "string",
            "format": "uuid"
          },
          "chain": {
            "type": "string",
            "enum": [
              "bsc",
              "polygon"
            ]
          },
          "buyer_email": {
            "type": "string",
            "format": "email"
          }
        }
      },
      "Balances": {
        "type": "object",
        "properties": {
          "by_chain": {
            "type": "object",
            "properties": {
              "bsc": {
                "type": "string"
              },
              "polygon": {
                "type": "string"
              }
            }
          },
          "currency": {
            "type": "string",
            "example": "USDT"
          },
          "pending_count": {
            "type": "integer"
          },
          "pending_total": {
            "type": "string"
          },
          "confirmed_count": {
            "type": "integer"
          },
          "confirmed_total": {
            "type": "string"
          }
        }
      }
    }
  }
}