Start a merchant's bank connection

POST/api/v1/credit/bank-connections

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.

Operation ID: create_credit_bank_connection·View as markdown·OpenAPI slice

Authentication

Bearer token authentication. Pass your DayZero API token in the Authorization header and the target business UUID in x-business-id.

Request body

Schema: BankConnectionStartRequest

program_idstring: Your program the merchant is applying under. Required without credit_line_id; with it, must be the line's program if sent.
external_merchant_idstring: 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_idstring: 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_namestring: 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_emailstring: 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_idstring: 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_uristring: 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.
reconnectboolean: 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

201Successful Response

Schema: SuccessEnvelope_BankConnectionResponse_

successboolean
messagestring
codestring
dataBankConnectionResponse

400Bad Request - Invalid input

Schema: ErrorResponse

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

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

Schema: ErrorResponse

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

403Forbidden - Insufficient permissions

Schema: ErrorResponse

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

404Not Found - Resource does not exist

Schema: ErrorResponse

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

422Validation Error

Schema: ErrorResponse

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

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

Schema: ErrorResponse

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

503Service Unavailable

Schema: ErrorResponse

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

Code samples

POST/api/v1/credit/bank-connections

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"
}'