Payment methods

Exchange authorized payment methods for an entity

Turns an authorization token from a bank login into stored payment methods on a named tenant, owner, vendor, applicant, or the company itself. Every account the login authorized is tokenized with the payment processor and saved as an ach payment method. Requires the payment_methods:write permission.

POST

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

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

The authorization token the bank login produced.

tokenstringrequired

The provider-level authorization token — with Plaid, the public_token its onSuccess callback gives you. Between 1 and 500 characters. Its format is the provider's; treat it as opaque.

Response

200 · The payment methods created from the token.

paymentMethodsPaymentMethod[]required

The payment methods that were created. One bank login can authorize several accounts, so this may hold more than one. Accounts already on file are skipped rather than duplicated, so the array can be shorter than the number of accounts authorized, and can be empty.

400 · `token` is missing, empty, or longer than 500 characters.

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.

422 · The token was accepted by the provider but resolved to no bank accounts.

500 · The payment processor rejected the call — it could not resolve the authorization token, or could not tokenize one of the accounts behind it. 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.

Where the token comes from

MagicDoor does not issue this token. Call Start payment method setup for an entity with mode: "bankAuth", run the returned publicToken through the provider's client-side SDK, let the account holder sign in to their bank, and send back the token the SDK gives you when it finishes.