Billing & FinOps

Preview — pending review

This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.

Upload a wire-transfer receipt for manual approval

POST
/scopes/{scopeId}/billing/transactions/{transactionId}/receipts/uploads

Uploads a SWIFT/EFT bank-transfer receipt for a wire-transfer transaction — both the initial "upload receipt · manual approval" step of the Pay-now wire flow and the "Upload a replacement receipt" control shown while a receipt is awaiting review. The file (PDF, PNG or JPEG) is sent as the RAW request body (not multipart); its display name comes from the fileName query parameter. The receipt's verification state is set to awaiting-review and the entry is (re-)queued for manual reconciliation by billing operations (SLA: 1 business day). A replacement upload supersedes the previous one and re-queues review. Validation: scope and transaction must exist and be visible (else NOT_FOUND); the transaction must still await resolution (pending / pending-manual-approval) and be a wire-transfer-pending or payment entry, and an existing receipt must not be verified — otherwise CONFLICT (a verified receipt is never re-opened); the body must be a non-empty PDF, PNG or JPEG (detected from its leading bytes, not from the name) of at most 10 MiB, otherwise VALIDATION_FAILED (field: file); the stored file name is sanitized (last path segment only, no path/HTML characters, at most 128 characters, extension matching the detected type); caller needs contributor/admin/owner or billing role, otherwise FORBIDDEN. Async & state: Conditional — the upload itself is accepted with 202 returning the stored WireReceipt in its transitional awaiting-review state; the downstream review transitions the receipt to terminal verified (transaction → completed) or rejection (transaction → failed). Review outcomes are emitted as resource.updated SSE frames with kind billing.transaction patching status and receipt.verification. Errors: 401 unauthenticated; 403 insufficient role; 404 unknown scope/transaction; 409 CONFLICT transaction state does not permit upload (already verified/settled); 422 wrong file type or oversize payload; 429 repeated uploads rate-limited; 500 object-store write failure. Idempotency/Concurrency: This operation does not use Idempotency-Key; it may be omitted and a sent one is ignored. The transaction is locked FOR UPDATE and holds one receipt, updated in place: a retried or repeated upload overwrites that receipt (file, name, size, awaiting-review) rather than attaching a second one or queuing a second review, and is refused with 409 CONFLICT once the receipt is verified.

Authorization

bearerToken
headerAuthorizationBearer <token>

An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

transactionId*string

Wire-transfer transaction ledger entry identifier.

Query Parameters

fileName?string

Display name of the receipt file (sanitized before it is stored); defaults to receipt.pdf.

Default"receipt.pdf"

Request Body

body*unknown

SWIFT/EFT receipt file (PDF).

Response Body

Receipt stored and queued for manual review; transitional receipt state returned.

application/json
  1. response

Metadata for an uploaded SWIFT/EFT bank-transfer receipt attached to a wire-transfer transaction.

fileName*string

Stored receipt file name (e.g. swift-receipt-9f31ad.pdf).

sizeKb*integer

File size in kilobytes.

uploadedAt*string
Formatdate-time
bank*string

Originating bank (e.g. "Barclays Bank — Canary Wharf, London").

iban*string

Beneficiary IBAN the transfer was sent to.

swiftRef*string

SWIFT reference of the transfer (e.g. BARCGB2284512).

verification*string

Manual reconciliation state; verified once matched against the bank feed.

Value in"awaiting-review""verified"
curl -X POST "https://example.com/scopes/string/billing/transactions/string/receipts/uploads"
{  "fileName": "string",  "sizeKb": 0,  "uploadedAt": "2019-08-24T14:15:22Z",  "bank": "string",  "iban": "string",  "swiftRef": "string",  "verification": "awaiting-review"}