Payment Methods
A signed-in donor's saved payment methods (the cards and US bank accounts they chose to keep) and the church and non-profit monthly gifts each one pays. Saving is opt-in, at checkout ("Save for next time") or from the profile. Every operation needs a signed-in caller. Reads also accept an API key; every change needs the person's own signed-in session, so an API key answers 403 SESSION_CREDENTIAL_REQUIRED and an administrator viewing the account answers 403 IMPERSONATION_RESTRICTED_ACTION. Ids are FundlyHub ids (SavedMethod.id and the monthly gift's id); Stripe's ids never appear. A method or gift that is not the caller's answers 404, exactly like one that does not exist. Refusals come as { "error": "…", "code": "…" }, and every answer is Cache-Control: private, no-store. A US bank account is verified instantly when the donor signs in to their bank; there is no micro-deposit step and no "waiting to verify" state.
List my saved payment methods and monthly gifts
The caller's live saved payment methods (the default first, then the
newest) and their live church and non-profit monthly gifts (newest
first), each with the saved method that pays it.
Reads accept any sign-in of the person, an API key or an administrator
viewing the account included.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Responses
The caller's methods and monthly gifts.
Start adding a payment method
A Stripe SetupIntent client secret for adding a card or a US bank
account from the profile, or for connecting Link (type link: a
card-only SetupIntent the page confirms from Stripe's Link button, so
the card Link pays with is saved as a link method). Collect the method in the browser with
Stripe.js confirmSetup using clientSecret, then call
POST /me/payment-methods/sync with the SetupIntent's id. The method
is kept for later off-session payments (monthly gifts). A US bank
account is verified instantly through the donor's bank sign-in; there
are no micro-deposits.
The caller's own signed-in session only. Limited to 10 an hour per
account, on top of the per-account 100 a minute.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Request Body
Responses
The SetupIntent's client secret.
Record a payment method added from the profile
Records the method a profile SetupIntent saved, once the browser's
confirmSetup has finished, and returns it. Stripe's
setup_intent.succeeded event records the same method, in either
order, so calling this twice, or after the event, returns the same
method. The donor's first saved method becomes their default.
The caller's own signed-in session only.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Request Body
Responses
The saved method.
Remove a saved payment method
Removes one of the caller's methods: it is detached from the caller's
Stripe customer, so nothing can charge it again, then taken off the
list. When it was the default, the newest remaining method that has
not expired becomes the default.
A method that live monthly gifts charge cannot be removed: the answer
is 409 used_by_monthly_gift with those gifts. Move them with
POST /me/payment-methods/{id}/move-gifts (or one at a time with
PATCH /me/monthly-gifts/{id}), then remove it again.
The caller's own signed-in session only.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Responses
Removed.
Make a saved payment method the default
Makes one of the caller's live methods their default; the previous
default stops being it. Making the current default the default changes
nothing. An expired card cannot be the default.
The caller's own signed-in session only.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Request Body
Responses
The method, now the default.
Move a method's monthly gifts to another method
Moves every live monthly gift that charges this method onto another
of the caller's saved methods, before removing this one. Each gift's
Stripe subscription charges the new method from its next payment. A
gift whose subscription has already ended is skipped and not counted.
Safe to repeat: a gift already moved no longer charges this method.
The target must be a live method of the caller, not an expired card,
and on the same Stripe customer as the gifts' subscriptions.
The caller's own signed-in session only.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
The method the gifts move off (SavedMethod.id).
"uuid"Request Body
Responses
How many gifts moved.
Change the method a monthly gift charges
Pays one of the caller's live church or non-profit monthly gifts with
another of their saved methods, from its next payment: the gift's
Stripe subscription takes the method as its default. Choosing the
method it already charges changes nothing. The method must be a live
method of the caller, not an expired card, and on the same Stripe
customer as the gift's subscription.
The caller's own signed-in session only.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
The monthly gift's id (MonthlyGiftSummary.id).
"uuid"Request Body
Responses
The gift, with its method.
Stop one of my monthly gifts
Stops one of the caller's own church or non-profit monthly gifts, the
same way the cancel link in the gift's receipt does. Past gifts stay as
they are. A gift that has already ended answers 200 as well.
The caller's own signed-in session only.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
The monthly gift's id (MonthlyGiftSummary.id).
"uuid"Responses
Stopped.