---
title: "Enroll Merchant"
method: POST
path: "/api/enroll_merchant"
tags: ["Enrollment"]
---

# Enroll Merchant

`POST /api/enroll_merchant`

Enroll a merchant in an alert or refund program. Send a `program` discriminator with that program's fields. `ethoca` and `cdrn` require `descriptors`. `rdr` requires `arns` and/or equal-length paired `bins`/`caids` (its `bins`/`caids` are persisted as queryable RDR descriptors). `amex` and `discover` require legal name, DBA, address, and their SE identifiers (they now persist a `Pending` descriptor you can poll). Enrollment files a request; records start `Pending` and become `Enrolled` once the provider-side enrollment confirms. Pass `merchant_id` to target a specific merchant, or omit it to create a brand-new merchant. Poll `GET /api/enrollment_status` for per-program state.

## Headers

- `X-API-Key` string, required

## Request body

- union
  - EnrollMerchantEthocaRequest
    - `program` 'ethoca', required — Program discriminator. Use `ethoca`.
    - `merchant_id` string, nullable — Existing merchant (retailer) id to enroll. Omit to create a brand-new merchant. The resolved id is returned as `merchantId`.
    - `ruleset` string, nullable — Optional refund / RDR threshold for the merchant (e.g. `<300`). When supplied and changed, a ruleset snapshot is recorded.
    - `descriptors` string[], required — Billing descriptors to enroll. At least one non-blank value is required. Stored uppercased.
  - EnrollMerchantCdrnRequest
    - `program` 'cdrn', required — Program discriminator. Use `cdrn`.
    - `merchant_id` string, nullable — Existing merchant (retailer) id to enroll. Omit to create a brand-new merchant. The resolved id is returned as `merchantId`.
    - `ruleset` string, nullable — Optional refund / RDR threshold for the merchant (e.g. `<300`). When supplied and changed, a ruleset snapshot is recorded.
    - `descriptors` string[], required — Billing descriptors to enroll. At least one non-blank value is required. Stored uppercased.
  - EnrollMerchantRdrRequest — RDR enrollment. Provide `arns`, and/or equal-length paired `bins`/`caids` (each bin needs a matching caid at the same index). Submitted `bins`/`caids` are persisted as queryable RDR descriptor records (returned in `descriptorIds` and listed by `GET /api/v2/descriptors`), starting `Pending` and becoming `Enrolled` once the provider-side enrollment confirms.
    - `program` 'rdr', required — Program discriminator. Use `rdr`.
    - `merchant_id` string, nullable — Existing merchant (retailer) id to enroll. Omit to create a brand-new merchant. The resolved id is returned as `merchantId`.
    - `ruleset` string, nullable — Optional refund / RDR threshold for the merchant (e.g. `<300`). When supplied and changed, a ruleset snapshot is recorded.
    - `arns` string[], nullable — Visa Acquirer Reference Numbers.
    - `bins` string[], nullable — Card BINs. Paired positionally with `caids` and persisted as RDR descriptor records.
    - `caids` string[], nullable — Card Acceptor IDs. Paired positionally with `bins` and persisted as RDR descriptor records.
  - EnrollMerchantAmexRequest
    - `program` 'amex', required — Program discriminator. Use `amex`.
    - `merchant_id` string, nullable — Existing merchant (retailer) id to enroll. Omit to create a brand-new merchant. The resolved id is returned as `merchantId`.
    - `ruleset` string, nullable — Optional refund / RDR threshold for the merchant (e.g. `<300`). When supplied and changed, a ruleset snapshot is recorded.
    - `legalName` string, required — Merchant legal name.
    - `dbaName` string, required — Doing-business-as name.
    - `amexSe` string, required — Amex Service Establishment (SE) number.
    - `amexDescriptor` string, required — Amex billing descriptor.
    - `streetAddress` string, required — Street address.
    - `city` string, required — City.
    - `state` string, required — State or province.
    - `country` string, required — Country.
    - `zip` string, required — Postal code.
  - EnrollMerchantDiscoverRequest
    - `program` 'discover', required — Program discriminator. Use `discover`.
    - `merchant_id` string, nullable — Existing merchant (retailer) id to enroll. Omit to create a brand-new merchant. The resolved id is returned as `merchantId`.
    - `ruleset` string, nullable — Optional refund / RDR threshold for the merchant (e.g. `<300`). When supplied and changed, a ruleset snapshot is recorded.
    - `legalName` string, required — Merchant legal name.
    - `dbaName` string, required — Doing-business-as name.
    - `discoverSe` string, required — Discover Service Establishment (SE) number.
    - `streetAddress` string, required — Street address.
    - `city` string, required — City.
    - `state` string, required — State or province.
    - `country` string, required — Country.
    - `zip` string, required — Postal code.

## Response `200`

Enrollment applied.

- EnrollMerchantResponse
  - `merchantId` string, required — The merchant (retailer) id this enrollment was applied to. Newly created or reused.
  - `merchantCreated` boolean, required — True if a new merchant was created for this request, false if an existing one was reused.
  - `program` string, required — The program that was enrolled (lowercased).
  - `descriptorIds` string[], required — Ids of descriptor records created or updated, retrievable via `GET /api/v2/descriptors`. Populated for Ethoca, CDRN, RDR (one per BIN/CAID pair), Amex, and Discover. Empty only when the program persisted no descriptor (e.g. an RDR enrollment sending `arns` alone).
  - `rulesetSnapshotId` string, nullable — Id of the ruleset snapshot recorded, or null if no ruleset change occurred.

## Other responses

- `400` — Validation failed. Unknown `program`, a missing required per-program field, or a body in the old `{ type, merchantId, requestData }` shape.
- `401` — Missing or invalid API key.
- `404` — A `merchant_id` was supplied but no merchant with that id belongs to this account.

---

[API](https://skmtc.net/chargeblast/apis/chargeblast-api.md) · [All operations](https://skmtc.net/chargeblast/apis/chargeblast-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/chargeblast/chargeblast-api/versions/9cc519753b33/schema)