Business Transitions
Use the /businesstransitions endpoints to transition business resources between states, as well as to retrieve and list state changes for a business resource.
Create business transition
Copy section link
Action: POST
Endpoint: /businesstransitions
This endpoint enables you to change a business' status, depending on your role and the previous status change.
By changing a business' status, you can control the business' capabilities and the setting of the business.active field.
The business.active field is true if your business is in the LIMITED or ACTIVE state, and false if your business is in the UNVERIFIED state.
You cannot control the value of the business.active field directly.
| The business.status field | Description | Business limitations |
|---|---|---|
Unverified |
Initial status of a newly created business belonging to an |
Cannot load funds. The business.active field: Allowable transitions: |
Limited |
Initial status of a newly created business belonging to an |
Restricted by rules in The business.active field: Allowable transitions: |
Active |
Status of a business that has passed KYC; initial status of a newly created business belonging to an |
None. The business.active field: Allowable transitions: |
Suspended |
The business is temporarily inactive. NOTE: Transitioning a suspended business to the |
Cannot load funds or activate cards. The business.active field: Allowable transitions: |
Closed |
The business is permanently inactive. NOTE: |
Cannot load funds. The business.active field: Allowable transitions: |
Note
The Marqeta platform transitions a business" status in response to certain events. For example, a business with anUNVERIFIED status transitions to ACTIVE when the business passes KYC.
Request body
Copy section link
| Fields | Description |
|---|---|
business_token
string
|
Unique identifier of the business whose status you want to transition. Allowable Values: Existing business resource token |
channel
string
|
Mechanism by which the transaction was initiated. Allowable Values:
|
idempotentHash
string
|
Unique hashed value that identifies subsequent submissions of the business transition request. Allowable Values: 255 char max |
reason
string
|
Additional information about the status change. Allowable Values: 255 char max |
reason_code
string
|
Identifies the standardized reason for the transition: 00: Object activated for the first time. 01: Requested by you. 02: Inactivity over time. 03: This address cannot accept mail or the addressee is unknown. 04: Negative account balance. 05: Account under review. 06: Suspicious activity was identified. 07: Activity outside the program parameters was identified. 08: Confirmed fraud was identified. 09: Matched with an Office of Foreign Assets Control list. 10: Card was reported lost. 11: Card information was cloned. 12: Account or card information was compromised. 13: Temporary status change while on hold/leave. 14: Initiated by Marqeta. 15: Initiated by issuer. 16: Card expired. 17: Failed KYC. 18: Changed to 19: Changed to 20: Change occurred prior to the normalization of reason codes. 21: Initiated by a third party, often a digital wallet provider. 22: PIN retry limit reached. 23: Card was reported stolen. 24: Address issue. 25: Name issue. 26: SSN issue. 27: DOB issue. 28: Email issue. 29: Phone issue. 30: Account/fulfillment mismatch. 31: Other reason. Allowable Values:
|
status
string
|
Specifies the new status of the business. Allowable Values:
|
token
string
|
Unique identifier of the business transition. If you do not include a token, the system generates one automatically. This token is referenced in other API calls, so we recommend that you define a simple string that is easy to remember. This value cannot be updated. Allowable Values: 36 char max |
Response body
Copy section link
| Fields | Description |
|---|---|
business_token
string
|
Unique identifier of the business whose status you want to transition. Allowable Values: Existing business resource token |
channel
string
|
Mechanism by which the transaction was initiated. Allowable Values:
|
created_time
datetime
|
Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
last_modified_time
datetime
|
Date and time when the resource was last updated, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
reason
string
|
Additional information about the status change. Allowable Values: 255 char max |
reason_code
string
|
Identifies the standardized reason for the transition: 00: Object activated for the first time. 01: Requested by you. 02: Inactivity over time. 03: This address cannot accept mail or the addressee is unknown. 04: Negative account balance. 05: Account under review. 06: Suspicious activity was identified. 07: Activity outside the program parameters was identified. 08: Confirmed fraud was identified. 09: Matched with an Office of Foreign Assets Control list. 10: Card was reported lost. 11: Card information was cloned. 12: Account or card information was compromised. 13: Temporary status change while on hold/leave. 14: Initiated by Marqeta. 15: Initiated by issuer. 16: Card expired. 17: Failed KYC. 18: Changed to 19: Changed to 20: Change occurred prior to the normalization of reason codes. 21: Initiated by a third party, often a digital wallet provider. 22: PIN retry limit reached. 23: Card was reported stolen. 24: Address issue. 25: Name issue. 26: SSN issue. 27: DOB issue. 28: Email issue. 29: Phone issue. 30: Account/fulfillment mismatch. 31: Other reason. Allowable Values:
|
status
string
|
Specifies the status of the business. Allowable Values:
|
token
string
|
Unique identifier of the business transition. Allowable Values: Existing business transition token |
List business transitions
Copy section link
Action: GET
Endpoint: /businesstransitions/business/{business_token}
List all transitions for a given business.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
business_token
string
|
Unique identifier of the business resource associated with the transitions to retrieve. Allowable Values: Existing business resource token |
URL query parameters
Copy section link
| Fields | Description |
|---|---|
count
integer
|
Number of business transitions to retrieve. Allowable Values: 1-10 Default value: |
start_index
integer
|
Sort order index of the first resource in the returned array. Allowable Values: Any integer Default value: |
fields
string
|
Comma-delimited list of fields to return ( Allowable Values: Comma-delimited list of fields, or blank |
sort_by
string
|
Field on which to sort.
Use any field in the resource model, or one of the system fields Allowable Values:
Default value: |
Response body
Copy section link
| Fields | Description |
|---|---|
count
integer
|
The number of resources retrieved. This field is returned if there are resources in your returned array. Allowable Values: 1-10 |
data
array of objects
|
Array of business transition objects. Objects are returned as appropriate to your query. Allowable Values: A valid array of one or more business transition objects |
data[].business_token
string
|
Unique identifier of the business whose status you want to transition. Allowable Values: Existing business resource token |
data[].channel
string
|
Mechanism by which the transaction was initiated. Allowable Values:
|
data[].created_time
datetime
|
Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].last_modified_time
datetime
|
Date and time when the resource was last updated, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].reason
string
|
Additional information about the status change. Allowable Values: 255 char max |
data[].reason_code
string
|
Identifies the standardized reason for the transition: 00: Object activated for the first time. 01: Requested by you. 02: Inactivity over time. 03: This address cannot accept mail or the addressee is unknown. 04: Negative account balance. 05: Account under review. 06: Suspicious activity was identified. 07: Activity outside the program parameters was identified. 08: Confirmed fraud was identified. 09: Matched with an Office of Foreign Assets Control list. 10: Card was reported lost. 11: Card information was cloned. 12: Account or card information was compromised. 13: Temporary status change while on hold/leave. 14: Initiated by Marqeta. 15: Initiated by issuer. 16: Card expired. 17: Failed KYC. 18: Changed to 19: Changed to 20: Change occurred prior to the normalization of reason codes. 21: Initiated by a third party, often a digital wallet provider. 22: PIN retry limit reached. 23: Card was reported stolen. 24: Address issue. 25: Name issue. 26: SSN issue. 27: DOB issue. 28: Email issue. 29: Phone issue. 30: Account/fulfillment mismatch. 31: Other reason. Allowable Values:
|
data[].status
string
|
Specifies the status of the business. Allowable Values:
|
data[].token
string
|
Unique identifier of the business transition. Allowable Values: Existing business transition token |
end_index
integer
|
Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
is_more
boolean
|
A value of This field is returned if there are resources in your returned array. Allowable Values:
|
start_index
integer
|
Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
Retrieve business transition
Copy section link
Action: GET
Endpoint: /businesstransitions/{token}
Use this endpoint to retrieve a business transition.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the business transition you want to retrieve. Allowable Values: Existing business transition token |
URL query parameters
Copy section link
| Fields | Description |
|---|---|
fields
string
|
Field on which to sort.
Use any field in the resource model, or one of the system fields Allowable Values:
|
Response body
Copy section link
| Fields | Description |
|---|---|
business_token
string
|
Unique identifier of the business whose status you want to transition. Allowable Values: Existing business resource token |
channel
string
|
Mechanism by which the transaction was initiated. Allowable Values:
|
created_time
datetime
|
Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
last_modified_time
datetime
|
Date and time when the resource was last updated, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
reason
string
|
Additional information about the status change. Allowable Values: 255 char max |
reason_code
string
|
Identifies the standardized reason for the transition: 00: Object activated for the first time. 01: Requested by you. 02: Inactivity over time. 03: This address cannot accept mail or the addressee is unknown. 04: Negative account balance. 05: Account under review. 06: Suspicious activity was identified. 07: Activity outside the program parameters was identified. 08: Confirmed fraud was identified. 09: Matched with an Office of Foreign Assets Control list. 10: Card was reported lost. 11: Card information was cloned. 12: Account or card information was compromised. 13: Temporary status change while on hold/leave. 14: Initiated by Marqeta. 15: Initiated by issuer. 16: Card expired. 17: Failed KYC. 18: Changed to 19: Changed to 20: Change occurred prior to the normalization of reason codes. 21: Initiated by a third party, often a digital wallet provider. 22: PIN retry limit reached. 23: Card was reported stolen. 24: Address issue. 25: Name issue. 26: SSN issue. 27: DOB issue. 28: Email issue. 29: Phone issue. 30: Account/fulfillment mismatch. 31: Other reason. Allowable Values:
|
status
string
|
Specifies the status of the business. Allowable Values:
|
token
string
|
Unique identifier of the business transition. Allowable Values: Existing business transition token |