Payment methods & mandates
Contents 26 pages
The API never accepts a card number. There is no card field on any endpoint and
no way to add a card over HTTP. Cards are added by a person, in a Stripe-hosted
form, at /portal/payment-methods;
GET /payment_methods/setup only answers that page's link. With
payments:write, a key may rename a card, choose who may use it, or remove it
(see Billing), but never allow it for unattended charges:
a person does that on the same page.
What the API does is let you name a card that has already been authorized for unattended charges.
A Shopify store pays through Shopify, so its key has no cards to list: GET /payment_methods answers not_available_for_shopify.
The extra permission your cards need#
A card saved in the web app is authorized for one thing: a person signing in and clicking Pay. That is what the wording said when it was saved, and we hold ourselves to it.
Booking over the API is a different thing — nobody is present when the money moves — so it needs its own, separate authorization, granted per card by a person with authority:
Allow API bookings. You authorize ShipEasy to charge this card for freight booked through this organization's API keys, with no one present to approve each charge. Any holder of a live API key for this organization can trigger a booking, and your organization is responsible for charges made with its keys. Turn this off here at any time, or revoke the keys.
Your existing cards do not have this. Nothing was migrated, nothing was inferred, and no bulk switch turned it on. Each card has to be enabled deliberately at /portal/payment-methods by an owner or admin, which involves briefly re-confirming the card with Stripe.
One deliberate step per card is the right amount of friction for authorizing charges nobody will be watching.
List the cards you can book with#
/api/v1/payment_methodsScope payments:read or bookings:writecurl https://app.shipeasyco.com/api/v1/payment_methods \
-H "Authorization: Bearer $SHIPEASY_API_KEY"{
"object": "list",
"data": [
{
"object": "payment_method",
"id": "cm2k7p3q0…",
"brand": "visa",
"last4": "4242",
"exp_month": 11,
"exp_year": 2028,
"funding": "credit",
"nickname": "Ops card",
"visibility": "organization",
"mit_enabled": true,
"expired": false,
"last_used_at": "2026-11-12T14:05:02.000Z",
"created_at": "2026-04-02T09:31:00.000Z"
},
{
"object": "payment_method",
"id": "cm2k7r1w6…",
"brand": "mastercard",
"last4": "8210",
"mit_enabled": false,
"expired": false,
…
}
],
"has_more": false,
"next_cursor": null
}Requires payments:read, or bookings:write so a key that books can name the
card it charges without reading invoices. Never returns a card number — brand, last four, expiry
and nothing else that could reconstruct one.
id is ShipEasy's id for the card, not Stripe's pm_… id. Send it as
payment.payment_method_id when booking.
Only mit_enabled: true cards can be used for API bookings. Passing any
other card's id to POST /bookings returns 402 card_not_enabled_for_api.
When exactly one card is enabled, a booking that names no card uses it; with
none enabled it returns 402 card_not_enabled_for_api, and with several it
returns 400 validation_failed on payment.payment_method_id.
expired is computed from the expiry against today, so you can warn before a
booking fails rather than after.
Which cards appear#
Only cards shared with the organization. A card someone saved privately for their own use while signed in is excluded — it was saved for that person, and an API key is not that person.
The list is also mode-scoped: a test key sees test cards, a live key sees live cards. That is why a test-mode integration cannot charge a real card even by sending the right id.
Most recently used first.
Booking with one#
{
"quote_id": "cm2k8r9f2…",
"payment": { "payment_method_id": "cm2k7p3q0…" },
…
}That is the whole payment side of a booking. See booking for the rest.
When a card is turned off#
Turning "Allow API bookings" off in the web app is immediate. The card stays saved and still works for someone signing in and clicking Pay; it simply stops appearing to the API as bookable, and any booking that names it is refused.
Revoking an API key does the same thing from the other direction, and is the faster move if a key has leaked: the card keeps working for people, and stops working for that key.
What we keep#
For each card enabled for API bookings we record when the authorization was given, which version of the wording was shown, who granted it, and Stripe's own mandate reference. That is what we would produce if a charge were ever disputed.
Errors#
| Code | ||
|---|---|---|
card_not_enabled_for_api |
402 | Not enabled for API bookings, or not a card this organization can book with (another organization's, private, removed, or the other mode). Someone with authority must enable it in the web app. |
card_declined |
402 | The issuer refused. Nothing was charged and nothing was booked. |
A bank challenge is not an error: POST /bookings answers 202 with
status: "requires_authentication". See
booking.