---
title: "Push a batch of payment records from SAP BTP"
method: POST
path: "/v2/integrations/providers/sap-btp/payments"
tags: ["integrations"]
---

# Push a batch of payment records from SAP BTP

`POST /v2/integrations/providers/sap-btp/payments`

## Request

- Base URL: `https://api.stuut.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.stuut.ai/v2/integrations/providers/sap-btp/payments`
- Auth: HTTP bearer

Maximum 100 records per request. Each payment carries allocations
linking it to the invoices/CMs it clears.

## Request body

- union[]
  - union
    - PaymentPayload: Standard payment; monetary values are in major currency units.
      - `custom_fields` object, nullable: Source-specific values without a standard field.
      - `journal_entry` string, required
      - `company_code` string, required
      - `fiscal_year` string, required
      - `customer_id` string
      - `amount` union, required
        - number
        - string, decimal
      - `currency` string, required
      - `date` string, date, required
      - `number` string, nullable
      - `description` string, nullable
      - `allocations` AllocationPayload[]
        - `invoice_number` string
        - `credit_memo_number` string
        - `fiscal_year` string, required
        - `company_code` string, required
        - `amount` union, required
          - number
          - string, decimal
    - SapBtpPaymentPayload: Payment record in the existing Honeywell iFlow format. Clearing cash rows have finite negative amounts and a document number equal to clearing_document_number; invoice rows have finite positive amounts. Document types are retained without an allowlist. Rows group by customer, company, currency, clearing document and clearing calendar year; each source document keeps its own fiscal year. A group requires one nonempty clearing date and cash rows from the same payment fiscal year. Missing or ambiguous identities fail. Standalone cash can resolve invoice_reference against stored invoice/source numbers within this connection, customer, company and currency. Exact literal identifiers take priority, including hyphenated numbers. Optional -INV/-REF suffixes and consecutive numeric ranges of at most 20 invoices are supported. Unresolved or over-capacity payments remain unapplied. Full matching amounts clear source lines; partial allocations await the invoice balance update. Identical retries preserve saved allocations after the invoice changes. A saved payment returns success=true, a Stuut ID, null message and error_code. Pending allocations and unapplied reasons are recorded in integration history. Unapplied cash is saved successfully; send missing invoices first, then resend the unchanged payment to retry resolution. Reconciliation conflicts return success=false and RECONCILIATION_ERROR; reconcile the stored payment before changing it.
      - `document_number` string, required: BELNR; payment doc number
      - `customer` string, nullable: KUNNR; may be empty for unapplied cash
      - `amount_in_lc` union, required: DMBTR; amount in local currency
        - number
        - string, decimal
      - `currency` string, required: WAERS; ISO 4217
      - `posting_date` string, date, required: BUDAT; posting date
      - `payment_reference` string, nullable: BELNR/KIDNO; wire ref, check #, ACH trace
      - `text` string, nullable: SGTXT; free-text memo
      - `allocations` SapBtpAllocationPayload[]: One entry per invoice/CM this payment clears
        - `invoice_number` string, nullable: BSEG-REBZG; invoice being cleared
        - `credit_memo_number` string, nullable: BSEG-REBZG; credit memo being consumed
        - `fiscal_year` string, required: BSEG-GJAHR; fiscal year of cleared document
        - `company_code` string, required: BSEG-BUKRS; company code of cleared document
        - `amount` union, required: BSEG-WRBTR; positive for invoices cleared, negative for CMs consumed
          - number
          - string, decimal
      - `custom_fields` object, nullable: SAP source metadata is preserved. invoice_reference drives standalone allocation and clearing as described in this schema. Expected keys: company_code, fiscal_year, line_item, document_type, posting_key, clearing_data, clearing_date, clearing_document_number, invoice_reference, original_invoice_no, original_invoice_amount, amount_in_usd, reason_code, payment_terms, dispute_status, disputed_invoice_amount, dispute_reason, dispute_root_cause, disputes_case_id

## Response `200`

Successful Response

- SapBtpInboundResponse: Common envelope for processing results and request-level errors. Request-level errors retain their HTTP status and return one failed result with an empty remote_id. No unauthenticated body is parsed to identify records. Validation failures retain their per-record results. Server errors expose a generic message; their exception reporting remains with the API.
  - `received_at` string, date-time, required
  - `results` SapBtpRecordResult[], required
    - `remote_id` string, required
    - `success` boolean, required
    - `stuut_id` string, nullable, required
    - `error_code` string, nullable, required
    - `message` string, nullable, required

## Other responses

- `401`: Missing or invalid bearer token.
- `403`: Access denied.
- `413`: Batch exceeds the record limit.
- `422`: Batch rejected; no records processed.
- `429`: Rate limit exceeded.
- `500`: Internal server error.
- `default`: Request failed.

---

[API](https://skmtc.dev/stuut/apis/stuut-api.md) - [All operations](https://skmtc.dev/stuut/apis/stuut-api/llms.txt) - [OpenAPI document](https://skmtc.dev/stuut/apis/stuut-api/revisions/ff0ad16a55ff?raw)