Payment methods

Start payment method setup for an entity

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

POST

https://services.magicdoor.com/payments/company-portal/methods/{entityType}/{entityId}/setup

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.

Path parameters

entityTypeenum<string>required

Who owns the payment method. company is the property management company itself, applicant is a rental applicant. Matching is case-insensitive.

example: tenantapplicanttenantownervendorcompany

entityIdstringrequired

The tenant, owner, vendor, applicant, or company that owns the payment method. A Snowflake id, sent as a decimal string.

example: 1812345678901234560

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.

404 · No tenant, owner, vendor, or company with that id. Applicant ids are not checked.

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.

Which methods this reaches

entityType and entityId name the party the payment method belongs to — a tenant, an owner, a vendor, a rental applicant, or the company itself. Whatever you name, the method must still belong to the calling company; one company can never reach another's. Passing company with your own company id reaches exactly the same methods as the endpoints without an entity in the path.

Applicants are not checked

For tenant, owner, vendor, and company the party is looked up before anything is stored, and an id that does not exist answers 404. applicant is not looked up at all, so an id that matches no rental applicant is accepted and the method is stored against it.

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 for an entity as source: "token", using the same entityType and entityId.
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 for an entity.