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
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.
bearerTokenAuthorizationBearer <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.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
transactionId*stringWire-transfer transaction ledger entry identifier.
fileName?stringDisplay name of the receipt file (sanitized before it is stored); defaults to receipt.pdf.
"receipt.pdf"body*unknownSWIFT/EFT receipt file (PDF).
Receipt stored and queued for manual review; transitional receipt state returned.
application/json- response
Metadata for an uploaded SWIFT/EFT bank-transfer receipt attached to a wire-transfer transaction.
fileName*stringStored receipt file name (e.g. swift-receipt-9f31ad.pdf).
sizeKb*integerFile size in kilobytes.
uploadedAt*stringdate-timebank*stringOriginating bank (e.g. "Barclays Bank — Canary Wharf, London").
iban*stringBeneficiary IBAN the transfer was sent to.
swiftRef*stringSWIFT reference of the transfer (e.g. BARCGB2284512).
verification*stringManual reconciliation state; verified once matched against the bank feed.
"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"}