Payment accounts
Connect, rename and disconnect the gateway accounts verified payments are paid into.
Verified payments are paid into your own Razorpay, Cashfree or
Stripe account. These endpoints manage those accounts. They need the payment
scopes, which no key preset includes: a key minted for anything else cannot
connect or disconnect where your money goes.
| Endpoint | Scope | What it does |
|---|---|---|
GET /v1/payment-accounts | payment:read | The connected accounts. Credentials are never returned |
POST /v1/payment-accounts/stripe | payment:write | Connect Stripe with a restricted key: { "restrictedKey": "rk_…" } |
POST /v1/payment-accounts/oauth/{provider}/start | payment:write | Start connecting razorpay or cashfree: { "returnTo" }, returns a consent url |
POST /v1/payment-accounts/cashfree/onboard | payment:write | Create a Cashfree account for a business that has none |
PATCH /v1/payment-accounts/{id} | payment:write | { "label" } to rename, { "isDefault": true } to make it the default |
DELETE /v1/payment-accounts/{id} | payment:write | Disconnect it |
curl -X POST https://api.chatform.in/v1/payment-accounts/stripe \
-H "x-api-key: $CHATFORM_SECRET_KEY" \
-H "content-type: application/json" \
-d '{"restrictedKey": "rk_live_…"}'The reply is { account }.
Good to know
- Stripe takes a restricted key only. A full
sk_secret key is a422withfull_secret_key. The key is tested before it is saved, and a missing permission is a422withmissing_permissionnaming it. The permissions it needs → - OAuth finishes in a browser. The consent
urlhas to be opened by the person who created the key, signed in to chatform. It is single-use and expires in ten minutes.returnTomust be a page on the chatform app. - Cashfree onboarding returns an
onboardingUrlfor Cashfree's KYC, or{ "useOAuth": true }when that email already has a Cashfree account. - Disconnecting revokes access at the gateway and deletes the stored credential. Forms still pointing at the account stop taking payments until you choose another.
- Plan. Connecting needs a plan that collects payments; without one it is a
402. A Stripe account already connected to another organization is a409. - The list is not paginated: it answers
{ accounts, enabled, providers }.
The payments themselves
GET /v1/forms/{id}/payments lists every checkout attempt on a form, newest
first, for reconciling against your gateway. It needs response:read, takes
status (default all) and response_id filters, and pages with a cursor like
every other list. Verified payments →