ASAP Payments API

openapi: 3.2.0
info:
  title: ASAP Platform Payments API
  description: 'Public HTTP API for ASAP Platform (api.asap.cool).


    All `/v1` responses are wrapped in a standard envelope. Success responses are `{ "data": , "meta": { "request_id", "next_cursor"?, "has_more"? } }` — the schema documented for each operation describes the inner `data` value. Errors are `{ "error": { "code", "message", "field"?, "request_id" } }`. Every response also carries an `X-Request-Id` header matching `meta.request_id` / `error.request_id`.'
  license:
    name: BUSL-1.1
  version: 0.0.0
servers:
- url: https://api.asap.cool
  description: Production
tags:
- name: Payments
  description: 'Payments hub reads: the connected account''s Stripe payouts (owner-only, read-only).'
paths:
  /v1/payments/bank-transactions:
    get:
      tags:
      - Payments
      summary: GET /v1/payments/bank-transactions
      operationId: listBankTransactions
      parameters:
      - name: status
        in: query
        description: Which credits to return; defaults to `pending`.
        required: false
        schema:
          $ref: '#/components/schemas/StatusParam'
      responses:
        '200':
          description: Imported credits in the requested status, each pending one with its proposal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankTransactionListView'
        '401':
          description: No active org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '403':
          description: Missing invoice:read scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - api_key:
        - invoice:read
      - session: []
  /v1/payments/bank-transactions/{id}/ignore:
    post:
      tags:
      - Payments
      summary: POST /v1/payments/bank-transactions/{id}/ignore
      operationId: ignoreBankTransaction
      parameters:
      - name: id
        in: path
        description: Bank credit identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The credit is set aside (also when it already was).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankTransactionView'
        '401':
          description: No active org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '403':
          description: Missing invoice:write scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '404':
          description: Credit not found, or cross-org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '409':
          description: '`bank_transaction_reconciled`: a payment points at the credit.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - api_key:
        - invoice:write
      - session: []
  /v1/payments/bank-transactions/{id}/reconcile:
    post:
      tags:
      - Payments
      summary: POST /v1/payments/bank-transactions/{id}/reconcile
      operationId: reconcileBankTransaction
      parameters:
      - name: id
        in: path
        description: Bank credit identifier.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReconcileRequest'
        required: true
      responses:
        '200':
          description: The credit was already reconciled against this document; nothing recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentStateView'
        '201':
          description: Payment recorded against the document; balance and status recomputed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentStateView'
        '401':
          description: No active org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '403':
          description: Missing invoice:write scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '404':
          description: Credit or document not found, or cross-org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '409':
          description: '`bank_transaction_ignored`, or `bank_transaction_reconciled` against another document.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '422':
          description: The document is not payable (quote, draft, credit note, terminal).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - api_key:
        - invoice:write
      - session: []
  /v1/payments/bank-transactions/{id}/unignore:
    post:
      tags:
      - Payments
      summary: POST /v1/payments/bank-transactions/{id}/unignore
      operationId: unignoreBankTransaction
      parameters:
      - name: id
        in: path
        description: Bank credit identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The credit is pending again (also when it already was).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankTransactionView'
        '401':
          description: No active org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '403':
          description: Missing invoice:write scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '404':
          description: Credit not found, or cross-org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '409':
          description: '`bank_transaction_reconciled`: a payment points at the credit.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - api_key:
        - invoice:write
      - session: []
  /v1/payments/payouts:
    get:
      tags:
      - Payments
      summary: '`GET /v1/payments/payouts`'
      operationId: stripeConnectPayouts
      responses:
        '200':
          description: Recent payouts of the org's connected account (empty when not connected).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutsView'
        '401':
          description: Caller is not a session owner of the active org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '503':
          description: Stripe Connect is not configured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
  /v1/payments/statements:
    post:
      tags:
      - Payments
      summary: POST /v1/payments/statements
      operationId: importBankStatement
      requestBody:
        description: 'multipart/form-data with a `file` part: a CSV, OFX or CAMT.053 bank statement (2 MiB, 5 000 lines at most). An optional `mapping` part holds a JSON `StatementMappingBody` and reads the file as a CSV with those columns.'
        content:
          multipart/form-data:
            schema:
              type: string
        required: true
      responses:
        '200':
          description: Statement read; counts of what was stored and dropped.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatementImportView'
        '401':
          description: No active org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '403':
          description: Missing invoice:write scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '422':
          description: 'Unreadable statement: `statement_too_large` (also for a body over the upload limit), `unrecognised_columns`, `statement_unreadable`, `invalid_mapping`, `malformed_multipart` or `missing_file_part`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - api_key:
        - invoice:write
      - session: []
  /v1/payments/statements/preview:
    post:
      tags:
      - Payments
      summary: POST /v1/payments/statements/preview
      operationId: previewBankStatement
      requestBody:
        description: multipart/form-data with a `file` part (a CSV statement) and an optional `delimiter` part (`;`, `,` or a tab) that overrides the guess.
        content:
          multipart/form-data:
            schema:
              type: string
        required: true
      responses:
        '200':
          description: The first rows of the file and the guessed delimiter and header position. Nothing is stored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatementPreviewView'
        '401':
          description: No active org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '403':
          description: Missing invoice:write scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '422':
          description: '`not_csv` (OFX and CAMT.053 need no mapping), `statement_too_large`, `statement_unreadable`, `invalid_mapping` (bad delimiter), `malformed_multipart` or `missing_file_part`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - api_key:
        - invoice:write
      - session: []
components:
  schemas:
    BankTransactionView:
      type: object
      description: One imported credit.
      required:
      - id
      - booked_on
      - amount_cents
      - currency
      - label
      - status
      properties:
        amount_cents:
          type: integer
          format: int64
          description: Amount in cents.
        booked_on:
          type: string
          description: Booking date, `YYYY-MM-DD`.
        currency:
          type: string
          description: Lower-case ISO currency code.
        document:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/BankDocumentView'
            description: Invoice the credit settled; present when reconciled.
        id:
          type: string
          format: uuid
          description: Credit identifier.
        label:
          type: string
          description: Bank label.
        proposal:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/BankProposalView'
            description: Proposed invoice; present on a pending credit that matches exactly one.
        status:
          type: string
          description: '`pending`, `reconciled` or `ignored`.'
    ReconcileRequest:
      type: object
      description: Body of `POST /v1/payments/bank-transactions/{id}/reconcile`.
      required:
      - document_id
      properties:
        document_id:
          type: string
          format: uuid
          description: 'Invoice or deposit the credit settles. Usually the proposal; any payable

            document of the org is accepted, which is how an unmatched credit is

            assigned by hand.'
    PayoutsView:
      type: object
      description: Response of `GET /v1/payments/payouts`.
      required:
      - connected
      - payouts
      properties:
        connected:
          type: boolean
          description: 'Whether the active org has a connected Stripe account. `false` yields an

            empty [`Self::payouts`] and signals the hub to show the connect CTA.'
        payouts:
          type: array
          items:
            $ref: '#/components/schemas/PayoutView'
          description: Recent payouts, most recent first. Empty when not connected.
    PayoutView:
      type: object
      description: One payout in the [`PayoutsView`] list. All amounts are integer centimes.
      required:
      - id
      - amount_cents
      - currency
      - status
      properties:
        amount_cents:
          type: integer
          format: int64
          description: Amount paid out, in centimes of [`Self::currency`].
        arrival_date:
          type:
          - integer
          - 'null'
          format: int64
          description: 'Expected/actual arrival date at the bank, as a Unix timestamp (seconds).

            `null` when Stripe has not scheduled one yet.'
        currency:
          type: string
          description: Lower-case ISO currency code (`eur`).
        id:
          type: string
          description: Stripe payout id (`po_…`), for display/correlation only.
        status:
          type: string
          description: 'Stripe payout status (`paid`, `pending`, `in_transit`, `canceled`,

            `failed`). Surfaced verbatim so the UI maps it to a tone/label.'
    PayableInvoiceView:
      type: object
      description: Invoice or deposit that still has a balance to collect.
      required:
      - document_id
      - number
      - remaining_due_cents
      properties:
        client:
          type:
          - string
          - 'null'
          description: Client display name, when the document carries one.
        document_id:
          type: string
          format: uuid
          description: Document identifier, as expected by `reconcile`.
        number:
          type: string
          description: Legal number.
        remaining_due_cents:
          type: integer
          format: int64
          description: Balance still due, in cents.
    StatementPreviewView:
      type: object
      description: The first rows of a CSV statement and a guess at how to read them.
      required:
      - delimiter
      - rows
      - suggested_skip_rows
      - column_count
      properties:
        column_count:
          type: integer
          description: Number of columns offered for mapping (the widest previewed row, capped).
          minimum: 0
        delimiter:
          type: string
          description: 'Delimiter in use: `;`, `,` or a tab.'
        rows:
          type: array
          items:
            type: array
            items:
              type: string
          description: The first non-blank rows, cells cut short. Contents come from the uploaded file.
        suggested_skip_rows:
          type: integer
          description: Rows before the first transaction (header included) that the parser would pick.
          minimum: 0
    PaymentView:
      type: object
      description: Public projection of a [`Payment`].
      required:
      - id
      - document_id
      - amount
      - paid_at
      - created_at
      properties:
        amount:
          type: integer
          format: int64
          description: Amount received, in cents.
        created_at:
          type: string
          description: RFC3339 creation timestamp.
        document_id:
          type: string
          format: uuid
          description: Document the payment settles.
        id:
          type: string
          format: uuid
          description: Stable identifier.
        method:
          type:
          - string
          - 'null'
          description: Payment method (free-form).
        paid_at:
          type: string
          description: RFC3339 settlement timestamp.
        reference:
          type:
          - string
          - 'null'
          description: Free-form payment reference.
    StatementImportView:
      type: object
      description: Outcome of a statement import. Every counter is a number of statement lines.
      required:
      - imported
      - duplicates
      - skipped_debits
      - skipped_currency
      properties:
        duplicates:
          type: integer
          format: int64
          description: Credits already stored by an earlier import (re-imported or overlapping file).
          minimum: 0
        imported:
          type: integer
          format: int64
          description: Credits stored by this import.
          minimum: 0
        skipped_currency:
          type: integer
          format: int64
          description: Credits in a currency other than euro, dropped.
          minimum: 0
        skipped_debits:
          type: integer
          format: int64
          description: Debits and zero-amount lines, dropped.
          minimum: 0
    ErrorBody:
      type: object
      description: 'Generic error body returned by API handlers when they fail. `code` is a

        stable machine-readable token; `message` is human-friendly and meant for

        surfacing to end users.'
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Stable machine token (e.g. `invalid_credentials`).
        field:
          type:
          - string
          - 'null'
          description: Offending request field for validation errors, when known.
        message:
          type: string
          description: Human-readable message.
    StatusParam:
      type: string
      description: Value of the `status` filter.
      enum:
      - pending
      - reconciled
      - ignored
    BankDocumentView:
      type: object
      description: Invoice a reconciled credit settled.
      required:
      - id
      - number
      properties:
        id:
          type: string
          format: uuid
          description: Document identifier.
        number:
          type: string
          description: Legal number.
    BankTransactionListView:
      type: object
      description: Response of `GET /v1/payments/bank-transactions`.
      required:
      - transactions
      - payable_invoices
      properties:
        payable_invoices:
          type: array
          items:
            $ref: '#/components/schemas/PayableInvoiceView'
          description: 'Documents a pending credit can be assigned to by hand; empty unless the

            `pending` status is requested.'
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/BankTransactionView'
          description: Credits in the requested status, newest first (200 at most).
    PaymentStateView:
      type: object
      description: The recomputed balance/status returned after a record or delete.
      required:
      - total_paid
      - remaining_due
      - status
      properties:
        payment:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/PaymentView'
            description: The recorded payment (present on `record`, absent on `delete`).
        remaining_due:
          type: integer
          format: int64
          description: '`total_ttc - total_paid`, in cents (negative on overpayment).'
        status:
          type: string
          description: Document status after the automatic paid/sent transition.
        total_paid:
          type: integer
          format: int64
          description: Sum of all payments against the document, in cents.
    BankProposalView:
      type: object
      description: Invoice a pending credit is proposed to settle.
      required:
      - document_id
      - number
      - confidence
      properties:
        client:
          type:
          - string
          - 'null'
          description: Client display name, when the document carries one.
        confidence:
          type: string
          description: '`exact` when the number appears in the label, `amount_only` when only the

            amount agrees.'
        document_id:
          type: string
          format: uuid
          description: Invoice or deposit identifier.
        number:
          type: string
          description: Legal number.
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
    session:
      type: apiKey
      in: cookie
      name: asap_session