Payment methods

Add a payment method

Adds a card or bank account for the company itself — the funding source MagicDoor charges the company's own fees to. The processor is asked to tokenize it, and the stored method carries only the brand, holder, last four digits, and expiry it reports back. A bank account gets both a collect and a payout capability where the processor allows it; a card gets collect only. Requires the payment_methods:write permission.

POST

https://services.magicdoor.com/payments/company-portal/methods

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

One of three shapes, chosen by source. The fields below are marked with the shape they belong to; only description is common to all three.

sourceenum<string>required

Which of the three shapes the rest of the body takes. token sends a short-lived token from the processor's own client-side SDK; card and ach send the raw numbers instead.

cardachtoken

descriptionstring

A free-text label kept with the method and returned as description. Accepted with all three shapes.

typeenum<string>

source: "token" only, and required there. Tells the API whether the token stands for a card or a bank account.

cardachdigitalWallet

tokenstring

source: "token" only, and required there. The short-lived token the payment processor's client-side SDK produced for the entered card or bank account. Its format is the processor's — treat it as opaque. Between 1 and 500 characters.

cardNumberstring

source: "card" only, and required there. The full card number, digits only, 13 to 19 of them. It must pass the Luhn check.

cardExpirystring

source: "card" only, and required there. The expiry as MM/YY, MM/YYYY, or MMYY. A month already past is rejected.

cardCvvstring

source: "card" only, and required there. The card security code, 3 or 4 digits.

cardHolderstring

source: "card" only, and required there. The name on the card, 1 to 200 characters.

cardZipstring

source: "card" only, optional. The billing postal code, at most 10 characters.

routingNumberstring

source: "ach" only, and required there. The bank's nine-digit ABA routing number. It must pass the ABA checksum.

accountNumberstring

source: "ach" only, and required there. The bank account number, digits only, 4 to 17 of them.

accountTypeenum<string>

source: "ach" only, and required there. The kind of bank account.

checkingsavings

holderNamestring

source: "ach" only, and required there. The name on the bank account, 1 to 200 characters.

Response

200 · The payment method that was added.

idstringrequired

The payment method. Send this value wherever a methodId is asked for. A Snowflake id, sent as a decimal string.

typeenum<string>required

What kind of funding source this is. ach is a US bank account reached by Automated Clearing House transfer.

cardachdigitalWallet

brandstring

The card network or bank brand the processor reported, for example "Visa". Absent when the processor reported none.

holderstring

The name on the card or bank account, as the processor reported it. Absent when the processor reported none.

last4string

The last four digits of the card or account number. The full number is never returned. Absent when the processor reported none.

expiresobject

The card expiry, month and year only. Absent for bank accounts, and for cards whose expiry the processor did not report.

cardTypeenum<string>

Whether the card draws on a bank balance or a credit line. Absent for bank accounts, and when the processor did not report it.

debitcredit

accountTypeenum<string>

The kind of bank account. Absent for cards, and when the processor did not report it.

checkingsavings

descriptionstring

The free-text label supplied when the method was added. Absent when none was given.

deactivatedstring · date-time

When the method was deactivated, in the company's timezone and without an offset. Absent while the method is usable.

isDeactivatedbooleanrequired

True when deactivated is present. A deactivated method stays on file but cannot be charged.

deactivationReasonstring

The reason given when the method was deactivated. Absent while the method is usable.

createdstring · date-timerequired

When the method was added, in the company's timezone and without an offset.

capabilitiesenum<string>[]required

What the method may be used for. collect takes money in, payout sends money out. Bank accounts normally get both; cards get collect only. The array is empty when the method has no capability with the processor MagicDoor currently runs.

collectpayout

400 · The body is missing a field its `source` requires, or a value failed its check — a card number that is not 13 to 19 digits or fails the Luhn check, an expiry that is malformed or already past, a CVV that is not 3 or 4 digits, a routing number that is not nine digits or fails the ABA checksum, or an account number that is not 4 to 17 digits.

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.

409 · The company already has this exact card or bank account on file with the processor.

422 · The processor tokenized the details but reported a different kind of instrument than the one asked for, for example a bank account where a card was sent.

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

Three ways to send the funding source

source: "card" and source: "ach" put the full card number or bank account number in the request body, so your own systems handle it. source: "token" does not: you call Start payment method setup, hand the returned publicToken to the processor's client-side SDK, collect the details in the SDK's own fields, and send back only the short-lived token it gives you.

Whichever you choose, it is on you to make sure the shape you send is one the processor supports for the operation you intend.