/businesstransitions endpoints to transition business resources between states, as well as to retrieve and list state changes for a business resource.
Create business transition
Action:POSTEndpoint:
/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 accountholdergroup where KYC is always required. | Cannot load funds. The business.active field: falseAllowable Transitions: ACTIVE, SUSPENDED, CLOSED, TERMINATED |
LIMITED | Initial status of a newly created business belonging to an accountholdergroup where KYC is conditionally required. | Restricted by rules in accountholdergroups.pre_kyc_controls.The business.active field: trueAllowable Transitions: ACTIVE, SUSPENDED, CLOSED |
ACTIVE | Status of a business that has passed KYC; initial status of a newly created business belonging to an accountholdergroup where KYC is never required. | None. The business.active field: trueAllowable Transitions: SUSPENDED, CLOSED |
SUSPENDED | The business is temporarily inactive. NOTE: Transitioning a suspended business to the ACTIVE status is restricted, based on your role and the details of the previous status change. | Cannot load funds or activate cards. The business.active field: falseAllowable Transitions: ACTIVE, LIMITED, UNVERIFIED, CLOSED, TERMINATED |
CLOSED | The business is permanently inactive. NOTE: CLOSED is a terminal status. In exceptional cases, you can transition a business from CLOSED to another status, depending on your role and the details of the previous status change. Contact your Marqeta representative for more information. | Cannot load funds. The business.active field: falseAllowable Transitions: ACTIVE, LIMITED, UNVERIFIED, SUSPENDED, TERMINATED |
TERMINATED | The business account is permanently closed. Use the TERMINATED state to comply with regulatory requirements, such as the requirement that a business account be irreversibly closed when it does not pass Know Your Business (KYB) verification.NOTE: TERMINATED is a terminal status. You must have the Admin or Program Manager role to transition a business to the TERMINATED state. You cannot transition a business from TERMINATED to any other state. Contact your Marqeta representative for more information.Allowable Transitions: None | Cannot load funds, activate cards, or transact. The business.active field: false |
Note
The Marqeta platform transitions a business’s status in response to certain events. For example, a business with an
The Marqeta platform transitions a business’s status in response to certain events. For example, a business with an
UNVERIFIED status transitions to ACTIVE when the business passes KYC.Request body
| Fields | Description |
|---|---|
| business_token string Required | Unique identifier of the business whose status you want to transition. Allowable Values: Existing business resource token |
| channel string Required | Mechanism by which the transaction was initiated. Allowable Values: API, IVR, FRAUD, ADMIN, SYSTEM |
| idempotentHash string Optional | Unique hashed value that identifies subsequent submissions of the business transition request. Allowable Values: 255 char max |
| reason string Optional | Additional information about the status change. Allowable Values: 255 char max |
| reason_code string Required | 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 ACTIVE because information was properly validated- 19: Changed to ACTIVE because account activity was properly validated- 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 - 32: Unblock request - 86: Notification of death Allowable Values: 00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 86 |
| status string Required | Specifies the new status of the business. Allowable Values: UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED, TERMINATED |
| token string Optional | 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 |
Sample request body
JSON
{
"token": "activate_05",
"business_token": "my_business_01",
"status": "ACTIVE",
"reason_code": "00",
"reason": "Activating business",
"channel": "API"
}
Response body
| Fields | Description |
|---|---|
| business_token string Conditionally returned | Unique identifier of the business whose status you want to transition. Allowable Values: Existing business resource token |
| channel string Returned | Mechanism by which the transaction was initiated. Allowable Values: API, IVR, FRAUD, ADMIN, SYSTEM |
| created_time datetime Conditionally returned | Date and time when the resource was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| last_modified_time datetime Conditionally returned | Date and time when the resource was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| reason string Conditionally returned | Additional information about the status change. Allowable Values: 255 char max |
| reason_code string Returned | 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 ACTIVE because information was properly validated- 19: Changed to ACTIVE because account activity was properly validated- 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 - 32: Unblock request - 86: Notification of death Allowable Values: 00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 86 |
| status string Returned | Specifies the status of the business. Allowable Values: UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED, TERMINATED |
| token string Returned | Unique identifier of the business transition. Allowable Values: Existing business transition token |
Sample response body
JSON
{
"token": "activate_05",
"business_token": "my_business_01",
"status": "ACTIVE",
"reason_code": "00",
"reason": "Activating business",
"channel": "API",
"created_time": "2022-09-23T23:28:39Z"
}
List business transitions
Action:GETEndpoint:
/businesstransitions/business/{business_token}
List all transitions for a given business.
URL path parameters
| Fields | Description |
|---|---|
| business_token string Required | Unique identifier of the business resource associated with the transitions to retrieve. Allowable Values: Existing business resource token |
URL query parameters
| Fields | Description |
|---|---|
| count integer Optional | Number of business transitions to retrieve. Allowable Values: 1-10 Default value: 5 |
| start_index integer Optional | Sort order index of the first resource in the returned array. Allowable Values: Any integer Default value: 0 |
| fields string Optional | Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.Allowable Values: Comma-delimited list of fields, or blank |
| sort_by string Optional | Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.Allowable Values: createdTime, lastModifiedTime, or any field in the resource modelDefault value: -id |
Response body
| Fields | Description |
|---|---|
| count integer Conditionally returned | 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 Conditionally returned | Array of business transition objects. Objects are returned as appropriate to your query. Allowable Values: Valid array of one or more business transition objects |
| data[].business_token string Conditionally returned | Unique identifier of the business whose status you want to transition. Allowable Values: Existing business resource token |
| data[].channel string Returned | Mechanism by which the transaction was initiated. Allowable Values: API, IVR, FRAUD, ADMIN, SYSTEM |
| data[].created_time datetime Conditionally returned | Date and time when the resource was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].last_modified_time datetime Conditionally returned | Date and time when the resource was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].reason string Conditionally returned | Additional information about the status change. Allowable Values: 255 char max |
| data[].reason_code string Returned | 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 ACTIVE because information was properly validated- 19: Changed to ACTIVE because account activity was properly validated- 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 - 32: Unblock request - 86: Notification of death Allowable Values: 00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 86 |
| data[].status string Returned | Specifies the status of the business. Allowable Values: UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED, TERMINATED |
| data[].token string Returned | Unique identifier of the business transition. Allowable Values: Existing business transition token |
| end_index integer Conditionally returned | 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 Conditionally returned | A value of true indicates that more unreturned resources exist. A value of false indicates that no more unreturned resources exist.This field is returned if there are resources in your returned array. Allowable Values: true, false |
| start_index integer Conditionally returned | 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 |
Sample response body
JSON
{
"count": 1,
"start_index": 0,
"end_index": 0,
"is_more": false,
"data": [
{
"token": "activate_05",
"business_token": "my_business_01",
"status": "ACTIVE",
"reason_code": "00",
"reason": "Activating business",
"channel": "API",
"created_time": "2022-11-23T23:28:39Z"
}
]
}
Retrieve business transition
Action:GETEndpoint:
/businesstransitions/{token}
Use this endpoint to retrieve a business transition.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | The unique identifier of the business transition you want to retrieve. Allowable Values: Existing business transition token |
URL query parameters
| Fields | Description |
|---|---|
| fields string Optional | Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.Allowable Values: createdTime, lastModifiedTime, or any field in the resource model |
Response body
| Fields | Description |
|---|---|
| business_token string Conditionally returned | Unique identifier of the business whose status you want to transition. Allowable Values: Existing business resource token |
| channel string Returned | Mechanism by which the transaction was initiated. Allowable Values: API, IVR, FRAUD, ADMIN, SYSTEM |
| created_time datetime Conditionally returned | Date and time when the resource was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| last_modified_time datetime Conditionally returned | Date and time when the resource was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| reason string Conditionally returned | Additional information about the status change. Allowable Values: 255 char max |
| reason_code string Returned | 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 ACTIVE because information was properly validated- 19: Changed to ACTIVE because account activity was properly validated- 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 - 32: Unblock request - 86: Notification of death Allowable Values: 00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 86 |
| status string Returned | Specifies the status of the business. Allowable Values: UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED, TERMINATED |
| token string Returned | Unique identifier of the business transition. Allowable Values: Existing business transition token |
Sample response body
JSON
{
"token": "activate_05",
"business_token": "my_business_01",
"status": "ACTIVE",
"reason_code": "00",
"reason": "Activating business",
"channel": "API",
"created_time": "2022-11-23T23:28:39Z"
}