# POST /api/v1/credit/bank-connections

> Start a merchant's bank connection

- **Tag:** credit
- **Operation ID:** `create_credit_bank_connection`

## Description

The Connect step of the Apply wizard (§9.3), and the Link button of Change Payment Method (§6.2). Name the merchant (`program_id` and `external_merchant_id` while it applies, or `credit_line_id` once it has a line). DayZero uses the merchant's DayZero business, creating it the first time, gives your token read access to it, and returns a hosted Plaid Link (`hosted_link_url`, `expires_at`) for the merchant to complete in your wizard. Nothing is emailed. While one is pending for the same merchant (or line), a repeat returns it with `created: false`. When the merchant finishes, `credit.bank_connection.completed` is emitted and the bank backfill underwriting waits on starts.

## Authentication

Bearer token in `Authorization` header.
Required header: `x-business-id: <business uuid>`.

## Request body

Schema: `BankConnectionStartRequest`

- `program_id` (string) — Your program the merchant is applying under. Required without `credit_line_id`; with it, must be the line's program if sent.
- `external_merchant_id` (string) — Your id for the merchant, as you will send it on `POST /credit/lines`. Required without `credit_line_id`. Every start for the same merchant uses the same DayZero business.
- `credit_line_id` (string) — An open line of yours (Change Payment Method, §6.2). The account the merchant chooses is recorded on it. The line's program and merchant are used; a different `program_id` or `external_merchant_id` is `400` `CREDIT_781`.
- `merchant_legal_name` (string) — Names the merchant's DayZero business when this call creates it. Defaults to the line's `merchant_legal_name`, else "Merchant <external_merchant_id>". Ignored when the business exists.
- `merchant_email` (string) — The merchant's email address, which Plaid asks for with the Link. DayZero does not email the merchant: the Link is returned to you. Defaults to the line's `merchant_email`; required when neither is there (`400` `CREDIT_785`).
- `merchant_business_id` (string) — The merchant's existing DayZero business, when it already keeps its books on DayZero and your token can reach it. Leave it out and DayZero uses the business this merchant was linked to before, or creates one. Naming another business than the one the merchant is linked to is `400` `CREDIT_788`.
- `completion_redirect_uri` (string) — Where Plaid sends the merchant when Link finishes, e.g. your wizard's next step. Must be one of the program's `bank_link_redirect_uris`, exactly (`400` `CREDIT_782` otherwise). Without it Plaid shows its own finished page.
- `reconnect` (boolean) — Repair the merchant's existing bank connection instead of linking a new bank: the Link is Plaid's update mode on the connection that needs the merchant to log in again (the one an assessment's `waiting_on: bank_reconnect` and `credit.bank_connection.reconnect_required` point at). The merchant's business must already exist; with no such connection it is `400` `CREDIT_779`. Completion is `credit.bank_connection.completed`, as for a new bank.

## Responses

### 201 — Successful Response

Schema: `SuccessEnvelope_BankConnectionResponse_`

- `success` (boolean)
- `message` (string)
- `code` (string)
- `data` (BankConnectionResponse)

### 400 — Bad Request - Invalid input

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

### 401 — Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

### 403 — Forbidden - Insufficient permissions

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

### 404 — Not Found - Resource does not exist

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

### 422 — Validation Error

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

### 429 — Too Many Requests - Rate limit exceeded; back off and retry

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

### 503 — Service Unavailable

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

## Code samples

### cURL

```bash
curl -X POST 'https://api.ondayzero.com/api/v1/credit/bank-connections' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "program_id": "string",
  "external_merchant_id": "string",
  "credit_line_id": "string",
  "merchant_legal_name": "string",
  "merchant_email": "string",
  "merchant_business_id": "string"
}'
```

### JavaScript

```javascript
const response = await fetch('https://api.ondayzero.com/api/v1/credit/bank-connections', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer dz_your_token',
    'x-business-id': 'YOUR_BUSINESS_ID',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "program_id": "string",
  "external_merchant_id": "string",
  "credit_line_id": "string",
  "merchant_legal_name": "string",
  "merchant_email": "string",
  "merchant_business_id": "string"
}),
});
const data = await response.json();
```

### Python

```python
import httpx

headers = {
    "Authorization": "Bearer dz_your_token",
    "x-business-id": "YOUR_BUSINESS_ID",
}

payload = {'program_id': 'string',
 'external_merchant_id': 'string',
 'credit_line_id': 'string',
 'merchant_legal_name': 'string',
 'merchant_email': 'string',
 'merchant_business_id': 'string'}

response = httpx.post("https://api.ondayzero.com/api/v1/credit/bank-connections", headers=headers, json=payload)
data = response.json()
```

## See also

- HTML version: https://www.ondayzero.com/docs/reference/credit/create-credit-bank-connection
- OpenAPI slice: https://www.ondayzero.com/docs/reference/credit/create-credit-bank-connection/openapi.json
- Other endpoints in **credit**: https://www.ondayzero.com/docs/reference/credit (markdown bundle: https://www.ondayzero.com/docs/reference/credit.md, OpenAPI: https://www.ondayzero.com/docs/reference/credit/openapi.json)
- Endpoint catalog: https://www.ondayzero.com/docs/reference/index.md