Payment Connect

Payment Connect provisions and manages the payment processing account for your project. Once connected, your store can accept payments through checkout and process payouts to your bank account.

Base URL: https://api.hydrajs.dev

Endpoints

Method	Path	Auth	Description
POST	/v1/store/payments/connect	Secret	Create a payment account
POST	/v1/store/payments/session	Secret	Create a payment session
POST	/v1/store/payments/disconnect	Secret	Disconnect payment account

---

Create a payment account

POST /v1/store/payments/connect

Provisions a payment account for the store. The store’s business country (from store settings) is used to configure the account. Returns 409 Conflict if an account is already connected.

Request

curl -X POST https://api.hydrajs.dev/v1/store/payments/connect \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 201

{
	"data": {
		"account_id": "acct_abc123def456",
		"status": "pending_kyc"
	}
}

Error 409 - already connected

{
	"error": {
		"code": "conflict",
		"message": "Payment account already connected"
	}
}

---

Create a payment session

POST /v1/store/payments/session

Creates an account session for embedded payment components (onboarding, payment management, payouts, documents). Use the returned client_secret with the embedded payment UI.

Request

curl -X POST https://api.hydrajs.dev/v1/store/payments/session \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
	"data": {
		"client_secret": "acss_secret_abc123...",
		"publishable_key": "pk_live_provider_key",
		"charges_enabled": true,
		"payouts_enabled": true,
		"details_submitted": true
	}
}

Field	Type	Description
client_secret	string	Session secret for embedded components
publishable_key	string	Publishable key for client-side payment UI
charges_enabled	boolean	Whether the account can accept charges
payouts_enabled	boolean	Whether payouts are enabled
details_submitted	boolean	Whether account onboarding is complete

Error 400 - no account

{
	"error": {
		"code": "invalid_request",
		"message": "No payment account connected. Create one first."
	}
}

---

Disconnect payment account

POST /v1/store/payments/disconnect

Clears the connected payment account so the merchant can set up a new one. This does not delete the account on the payment provider’s side.

Request

curl -X POST https://api.hydrajs.dev/v1/store/payments/disconnect \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
	"data": {
		"disconnected": true
	}
}

Error 400 - no account

{
	"error": {
		"code": "invalid_request",
		"message": "No payment account connected."
	}
}