Start payment method setup

Starts a processor-hosted flow for adding a payment method to the company itself, and returns what the processor's client-side SDK needs to open it. Requires the payment_methods:write permission.

Authorization

Authorizationstringrequired

Bearer token — Send your API token in the Authorization header as Bearer <token>. Requests without a valid token are rejected with 401 Unauthorized.

Body

application/json

Which flow to start. A JSON body is required — send {} to take the default.

modeenum<string>

card, ach, and digitalWallet collect the details in the processor's own fields and end with a token you send to Add a payment method. bankAuth runs a bank login instead and ends with an authorization token you send to Exchange authorized payment methods.

default: cardcardachdigitalWalletbankAuth

Response

200 · What the client-side SDK needs to open the flow.

providerenum<string>required

Which provider's client-side SDK the rest of this response is for. payabli collects card and bank details in its own fields; plaid runs a bank login.

payabliplaid

modeenum<string>required

The flow that was started, echoing the mode you asked for.

cardachdigitalWalletbankAuth

expiresstring · date-time

When the setup stops being usable, in the company's timezone and without an offset. Absent when the provider set no expiry.

publicTokenstringrequired

The provider-level token the client-side SDK needs to start — a public token, client secret, or session id depending on the provider. Its format is the provider's; treat it as opaque and do not parse it.

metadataobject

Extra provider-specific string keys and values for initialising the SDK. Both keys and values are the provider's — pass them through unchanged. Absent when the provider supplied none.

400 · The request carried no JSON body, or `mode` is not one of the four values.

401 · The request carried no valid access token.

403 · The token is not a property manager token, or it lacks the `payment_methods:write` permission.

500 · The payment processor rejected the call — it could not open a setup session. The `detail` member carries a summary that is safe to show a user; the provider's own diagnostic text is not returned.

Two endings, two follow-up calls

This call only starts the flow — nothing is stored yet, and no payment method exists until you come back.

With card, ach, or digitalWallet the SDK hands you a short-lived token for the instrument. Send it to Add a payment method as source: "token".
With bankAuth the SDK hands you an authorization token for a bank login, which can cover more than one account. Send it to Exchange authorized payment methods.