Payments accounts API - HubSpot docs

Scope requirements

Use the payments accounts API to check the state of the payments account connected to your HubSpot account. The response tells you whether the account can process transactions and receive payouts, where it is in the enrollment process, which payment processors it’s eligible to use, and when it last processed a transaction. This API is read-only. Check this endpoint before building flows that collect payment, such as payment links or quotes, to confirm that the account is able to transact.

Prerequisites

This API requires OAuth authentication. If you don’t yet have an app configured for OAuth, follow the OAuth quickstart guide to get started.
To use this API, you’ll need to enroll your account into the beta.

Retrieve payments account status

To retrieve the status of your payments account, make a GET request to /commerce/payment-accounts/2026-09-beta/status. The endpoint takes no parameters. It returns the payments account for the HubSpot account associated with your authentication token, and the response resembles the following:

{
  "id": "8675309",
  "createdAt": "2022-08-04T18:41:56.555Z",
  "updatedAt": "2025-10-21T13:26:23.243Z",
  "lastTransactedAt": "2026-07-31T18:02:14.199Z",
  "canPayout": true,
  "canTransact": true,
  "processorType": "HS_PAYMENTS",
  "enrollmentState": "ACTIVE",
  "eligibleProcessorTypes": [
    "BYO_STRIPE"
  ],
  "hasTransacted": true
}

Field	Type	Description
`id`	String	The ID of the HubSpot account that the payments account belongs to.
`createdAt`	String	The date and time when the payments account was created, in ISO 8601 format.
`updatedAt`	String	The date and time when the payments account was last updated, in ISO 8601 format.
`canPayout`	Boolean	Whether the account can pay out funds to the merchant’s bank.
`canTransact`	Boolean	Whether the account can accept payments from buyers.
`enrollmentState`	String	The current enrollment state of the payments account. See enrollment states below.
`processorType`	String	The payment processor currently connected to the account, and returns `NOT_ENROLLED` when there’s no active payments account. See processor types below.
`eligibleProcessorTypes`	Array	The payment processors that the account can still sign up for. In the example above, the account is currently enrolled in HubSpot payments and would be eligible for connecting its own Stripe account. See processor types below.
`lastTransactedAt`	String	The date and time of the most recent transaction processed by the account, in ISO 8601 format.
`hasTransacted`	Boolean	Whether any payment transaction has ever occurred in the HubSpot account.

Enrollment states

enrollmentState is a single lifecycle state covering both HubSpot payments and connected Stripe accounts. Use processorType to determine which of the two applies, since some states only ever occur for one of them.

Value	Applies to	Description
`NOT_STARTED`	Both	No payments account exists for the HubSpot account yet. `processorType` is `NOT_ENROLLED`, both `canTransact` and `canPayout` are `false`, and `eligibleProcessorTypes` lists all available processors.
`IN_PROGRESS`	Both	Setup has begun but isn’t finished. For HubSpot payments, identity verification information is still being collected. For a connected Stripe account, the connection has been started but isn’t enabled yet.
`IN_UNDERWRITING`	HubSpot payments	The application has been submitted and is awaiting underwriting review.
`ACTIVE`	Both	The account has been approved and enabled.
`SUSPENDED`	Both	The account is enrolled but has been disabled by HubSpot or by Stripe, for example following a risk or policy review. `canTransact` and `canPayout` are both `false` in this state.
`REJECTED`	HubSpot payments	The account didn’t clear underwriting.
`OPTED_OUT`	Connected Stripe	The merchant voluntarily left.
`DISCONNECTED`	Both	The account was disconnected.

To start or complete enrollment, follow the steps for setting up payments in HubSpot. Enrollment can’t be started or updated through the API.

The response describes the account’s current active payments account only. If a HubSpot account previously used a payments account that’s no longer active, that history isn’t reflected here. An account whose only prior payments account was disconnected reports NOT_STARTED.

Processor types

The processorType and eligibleProcessorTypes fields return the following values.

Value	Description
`NOT_ENROLLED`	No payment processor is connected to the account. Returned by `processorType` only.
`HS_PAYMENTS`	The account uses HubSpot payments as its processor.
`BYO_STRIPE`	The account uses its own connected Stripe account as its processor.

​Prerequisites

​Retrieve payments account status

​Enrollment states

​Processor types

Prerequisites

Retrieve payments account status

Enrollment states

Processor types