Pay an invoice

post

https://api.wingspan.app/v3/payments/invoices/{invoiceId}/pay

Initiates durable Invoice collection. The service jointly resolves a reusable funding source and authorization, or consumes request-scoped one-time evidence. A saved card is accepted from a linked Payer or from a Client-owned card whose subject is the Payer Account. The request reserves the Invoice before creating a deterministically referenced Funds Movement; retries recover the same payment. Direct collection of an Invoice carrying collaborator splits returns 409 until route-aware collaborator settlement is implemented. When the payer has archived its side of the invoice's engagement, a collection the payee starts returns 409 payments.EngagementPayerArchived; only the payer can pay it.

Requires a session with recent MFA step-up for HighRiskWriteAction. If step-up is missing or expired, this operation returns 403 StepUpMfaRequired; create and verify an MFA challenge at /v3/platform/mfa-challenges with requiredFor: "HighRiskWriteAction", then retry.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

invoiceId

string

required

Body Params

Initiate a full payment. Eligible invoice-collection workflows may resolve a reusable funding-source/mandate pair or accept an explicit funding source under that workflow's ownership and subject rules.

amount

double

Omit to pay the full Payable amount. If supplied, it must equal the full amount.

method

string

enum

Phase-one disbursement settles by ACH regardless of whether the saved funding source is an ExternalBankAccount or PaymentCard. Book is derived on reads and is not accepted here.

Allowed:

fundingSource

object

Reference to a saved payer-owned funding resource. Funding resources are always created before use on this path; raw bank/card details and one-off tokenization handles are never accepted here. Internal-account funding remains deliberately unspecified.

mandate

object

One-time mandate for the InvoicePayment created by this request. Must be supplied with an explicit fundingSource.

shouldEnableAutoPay

boolean

Defaults to false

A linked Payer may set true while paying to save the selected relationship-scoped source and consent to later Client-initiated automatic collection. Unlinked Payers and Client callers cannot enable it.

Headers

Idempotency-Key

string

required

length between 1 and 255

^[\x21-\x7e]{1,255}$

REQUIRED idempotency token for money-moving requests (e.g. transfers). The token is used by the API so a retry after a 5xx/timeout replays the original result instead of moving funds twice. Reuse the same key to retry safely; use a NEW key to issue a genuinely new transfer. Use 1-255 printable ASCII characters.

If-Match

string

required

Strong ETag from the latest resource GET or write response.

X-Wingspan-Account

string

^(?:[A-Za-z0-9_.]{22}|[a-f0-9]{24})$

Select the Account for an Account-scoped operation. A direct ServiceAccount API key MUST supply this header, and the target must be within the ServiceAccount owner's or Authorization grant's Account boundary. A Person bearer may select an Account on which it has an active Stakeholder, and an Account session may select its bound Account (or a descendant only when the session explicitly includes descendants).

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

Language

Credentials

Bearer

JWT

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

application/problem+json

200Payment initiated

400Malformed request syntax

401Unauthenticated

403Forbidden or step-up MFA required

404Resource not found

409Conflict

412Optimistic-concurrency precondition failed (If-Match mismatch)

422Validation error