> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swervpay.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Merchant Controls

> Add or remove one merchant ID from a USD card whitelist or blacklist

Add or remove **one merchant ID (MID)** from a card's whitelist or blacklist.
Use the Swerv card ID in the URL. The card must belong to your authenticated
business and be an active or frozen USD card.

| List | Purpose |
| - | - |
| `whitelist` | Restrict card payments to listed merchants, subject to all other card checks. |
| `blacklist` | Block card payments at listed merchants. |

Obtain the exact MID from the merchant or payment processor. Send it as a string,
preserving leading zeros. A merchant name, website, or merchant category code is
not a substitute. Different acquiring processors may use different MIDs for the
same merchant.

```bash cURL theme={null}
curl -X PATCH https://api.swervpay.co/api/v1/cards/card_123/merchants \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"list":"blacklist","action":"add","merchant_id":"243815000157182"}'
```

Use `action: "remove"` to remove that MID from the selected list. These operations
do not replace a whole list or change the other list. Submit one MID per request;
bulk arrays are not accepted. MID strings must be 1-64 printable ASCII characters,
without leading or trailing whitespace.

> [!WARNING]
>
> Avoid placing the same merchant in both lists. Do not depend on an undocumented
> precedence rule. Whitelisting a merchant does not override insufficient funds,
> frozen-card status, compliance checks, or other restrictions.

HTTP 200 confirms a successful control update. It does not create, fund, debit,
or unfreeze the card. Your existing fee schedule is unchanged.
No new webhook event is emitted for this operation, and
the card-detail response does not currently include these lists.

If the response says the outcome is unresolved, contact support before retrying.
A timeout can occur after the change was applied. Do not assume an error means
the old rule remains in effect. Provide the Swerv card ID, operation and request
time, never card credentials or authentication secrets.

In sandbox, these operations save simulated configuration without contacting
the live card network. Sandbox transaction fixtures do **not** simulate merchant
authorization or guarantee live approval/decline behavior.


## OpenAPI

````yaml PATCH /cards/{id}/merchants
openapi: 3.0.0
info:
  title: Swervpay Developer API Specification
  version: 0.0.0
servers:
  - url: https://api.swervpay.co/api/v1
    description: Production API
  - url: https://sandbox.swervpay.co/api/v1
    description: Sandbox API
security:
  - bearerAuth: []
paths:
  /cards/{id}/merchants:
    patch:
      tags:
        - card.controls
      description: Add or remove one merchant ID from a USD card whitelist or blacklist
      operationId: updateCardMerchant
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenapiCardMerchantRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseSuccessResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsererrorError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsererrorError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsererrorError'
components:
  schemas:
    OpenapiCardMerchantRequest:
      required:
        - list
        - action
        - merchant_id
      type: object
      properties:
        action:
          enum:
            - add
            - remove
          type: string
        list:
          enum:
            - whitelist
            - blacklist
          type: string
        merchant_id:
          maxLength: 64
          minLength: 1
          type: string
    ResponseSuccessResponse:
      type: object
      properties:
        message:
          type: string
    UsererrorError:
      type: object
      properties:
        message:
          type: string
        values:
          type: object
          additionalProperties: {}
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.