Setup Payment Method
Step 1 of payment method setup — get the client secret or approval URL
Initializes payment method setup for a billing customer. For Stripe, creates a SetupIntent and returns the `client_secret` for use with Stripe.js `confirmCardSetup()`. For PayPal, creates a vault order and returns the `approval_url` for the customer to authorize. Creates or updates the billing customer record.
Requires a valid `api_key` in the JSON request body
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
api_key |
body | string |
Yes | Your API key. |
org_id |
body | string |
Yes | Organization UUID. |
brand_id |
body | string |
Yes | Brand UUID. |
contact_id |
body | string |
Yes | The CRM contact UUID. |
gateway |
body | string |
No | Payment gateway: `stripe` or `paypal`. If omitted, auto-detected from subscription settings or active integrations. |
bc_id |
body | string |
No | Existing billing customer ID to update. If omitted, creates a new billing customer. |
Response
200
Stripe setup initialized
json
{
"data": {
"gateway": "stripe",
"client_secret": "seti_xxx_secret_xxx",
"publishable_key": "pk_live_xxx",
"setup_intent_id": "seti_xxx",
"stripe_customer_id": "cus_xxx",
"billing_customer_id": "bc_xxx"
},
"status": "success"
}
200
PayPal setup initialized
json
{
"data": {
"gateway": "paypal",
"order_id": "PAYPAL_ORDER_xxx",
"approval_url": "https://www.paypal.com/checkoutnow?token=xxx",
"billing_customer_id": "bc_xxx"
},
"status": "success"
}
Important:
This is Step 1 of a two-step process. After the customer completes the Stripe card form or PayPal authorization, call `/public/edge/confirmPaymentMethod` (Step 2) to finalize and activate the billing customer.
Tip:
Gateway auto-detection checks in order: explicit `gateway` parameter, subscription settings allowed gateways, then active Stripe or PayPal integrations. If no gateway is found, the endpoint returns an error.
