Payment and payout methods

This page explains the two sides of every payment: the payment method you pay from, and the payout method your payee is paid to. It shows how to add and manage payment methods through the API, which V1 only allowed in the app.

Payment methods: what you pay from

A payment method is an instrument your Account owns. Wherever the API asks for one, you pass a reference, { "type": "...", "id": "..." }, never raw bank or card numbers.

Where each one is used:

• Paying one payable names its instrument on the request: fundingSource on POST /v3/payments/payables/{payableId}/pay, with type ExternalBankAccount or PaymentCard. See Create a payable.
• Payroll runs debit the funding source on your payer settings. See Payroll settings and funding.
• defaultPaymentMethod on your payer settings is a convenience default that prefills a choice. It never pays anything on its own.

Add a bank account

Link a bank account with POST /v3/finance/external-bank-accounts. Idempotency-Key is required, so a retry can't create a duplicate account or a second round of micro-deposits. You can:

• Use a bank-linking flow. Get a temporary token from POST /v3/finance/external-bank-accounts/link, have the account holder complete the flow, then create the account from the token it returns. Accounts linked this way can start Verified.
• Enter routing and account numbers directly. The account then needs micro-deposit verification. Wingspan sends two small deposits, and you confirm the amounts with POST /v3/finance/external-bank-accounts/{bankAccountId}/verify.

Payroll needs a bank account that's verified, set to Business or Mixed usage, and enabled for payments. See Payroll settings and funding.

Important: Only send bank account numbers from your server over HTTPS, and never log them. Prefer the bank-linking flow so account numbers don't pass through your systems.

Add a card

Cards are captured in a hosted frame so card numbers never reach your servers or Wingspan's API.

1. Create a pending card with POST /v3/payments/payment-cards. The body takes only externalId and metadata.
2. Get a short-lived credential for the hosted card form with POST /v3/payments/payment-cards/{paymentCardId}/link, and show the form to the cardholder.
3. Activate the card with POST /v3/payments/payment-cards/{paymentCardId}/activate. Wingspan runs a zero-amount verification and activates the card only if it matches.

List cards with GET /v3/payments/payment-cards and remove one with DELETE /v3/payments/payment-cards/{paymentCardId}.

These are cards your own Account pays with. If you get paid by clients and want to save a client's card so you can charge it, use a card setup instead. See Save your client's card.

Use your Wallet

Your Wingspan Wallet is an InternalAccount. List it with GET /v3/finance/internal-accounts and use its id as a payroll funding source with type: InternalAccount. Add money to it before you finalize a run it funds.

A service account or API key that reads your Wallet or its statements needs the bookkeeping.business-banking-account:read scope. Reading its balance needs bookkeeping.business-banking-balance:read, and listing its transactions needs bookkeeping.transaction:read. Creating an internal account or moving money between internal accounts needs bookkeeping.business-banking-account:write.

Payout methods: where your payees get paid

A payout method belongs to the payee side. When you pay a payable, Wingspan sends the payout to wherever the payee is set up to receive it:

• A payee with their own Wingspan Account manages their own payout methods: bank accounts, debit cards, the Wallet, and how payouts are split between them. See Payout methods.
• A payee who hasn't linked an Account can be paid through payout routing you manage for them with POST /v3/payments/payout-settings. Every destination must be an external bank account you added for that payee, and destinations are split by percentage.

A payee with no usable payout method can't be paid, and their payables sit in Pending. See Find incomplete payables.

Security

Changing where money comes from or goes to is protected. Changing your payroll funding source requires recent multi-factor authentication; without it you get 403 with code: StepUpMfaRequired. Paying a payable and finalizing a payroll run are protected the same way.

Common mistakes

• Sending raw bank or card details to a payment endpoint. Payment endpoints accept only saved instrument references.
• Expecting defaultPaymentMethod to fund payroll. It doesn't. Set payrollSettings.defaultFundingSource.
• Linking an unverified account for payroll. Complete micro-deposit verification first.
• Changing the payee's payout method from the payer side. A linked payee controls their own payout methods.

Related pages

• Payroll settings and funding
• Payout methods
• Collect payment for paying invoices you receive with a debit authorization