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

# Replace Card

> Replace a card with a new one — same cardholder, new card number. POST /cards/{cardId}/replace.

## Overview

Replace an existing card with a brand new one. The `cardId` remains the same for your records, but the card details (number, expiry, CVV) are replaced with a completely new card. Any remaining balance is automatically transferred to the new card.

<Warning>
  The old card will be immediately terminated and cannot be used after replacement. All future transactions must use the new card details.
</Warning>

## Use Cases

* **Card Compromised**: When a cardholder reports unauthorized use or data exposure
* **Card Lost**: When a physical card is lost and needs to be replaced
* **Card Damaged**: When the card details are no longer accessible

## Path Parameters

| Parameter | Type   | Description                |
| --------- | ------ | -------------------------- |
| `cardId`  | string | The unique card identifier |

## Request Body (Optional)

| Field       | Type   | Required | Description                                                                                                                 |
| ----------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `reason`    | string | No       | Reason for replacing the card (e.g., "Card compromised", "Card lost")                                                       |
| `reference` | string | No       | Your unique reference for this operation. Defaults to cardId if not provided. Returned in webhooks for easy reconciliation. |

## Example Usage

<CodeGroup>
  ```php PHP theme={null}
  <?php
  $cardId = 'crd_8f3a2b1c4d5e6f7890abcdef12345678';
  $data = [
      'reason' => 'Card compromised',
      'reference' => 'replace-card-abc123'  // Optional: your unique reference
  ];

  $ch = curl_init("https://api.fyatu.com/api/v3/cards/{$cardId}/replace");
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          'Authorization: Bearer ' . $accessToken,
          'Content-Type: application/json'
      ],
      CURLOPT_POSTFIELDS => json_encode($data)
  ]);

  $response = curl_exec($ch);
  $result = json_decode($response, true);

  if ($result['success']) {
      echo "Card replaced successfully!\n";
      echo "New Last 4: " . $result['data']['last4'] . "\n";
      echo "New Expiry: " . $result['data']['expiryDate'] . "\n";
      echo "Balance Transferred: $" . $result['data']['balance'] . "\n";
      echo "Reference: " . $result['data']['reference'] . "\n";
  }
  ```

  ```javascript Node.js theme={null}
  const cardId = 'crd_8f3a2b1c4d5e6f7890abcdef12345678';

  const response = await fetch(`https://api.fyatu.com/api/v3/cards/${cardId}/replace`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      reason: 'Card compromised',
      reference: 'replace-card-abc123'  // Optional: your unique reference
    })
  });

  const result = await response.json();
  if (result.success) {
    console.log('Card replaced successfully!');
    console.log('New Last 4:', result.data.last4);
    console.log('New Expiry:', result.data.expiryDate);
    console.log('Balance Transferred: $' + result.data.balance);
    console.log('Reference:', result.data.reference);
  }
  ```
</CodeGroup>

## Response Fields

| Field          | Type   | Description                                      |
| -------------- | ------ | ------------------------------------------------ |
| `id`           | string | The card identifier (unchanged from before)      |
| `cardholderId` | string | The cardholder identifier                        |
| `name`         | string | Name on the card                                 |
| `last4`        | string | Last 4 digits of the **new** card number         |
| `maskedNumber` | string | Masked **new** card number                       |
| `expiryDate`   | string | **New** card expiry date (MM/YYYY)               |
| `brand`        | string | Card brand (VISA or MASTERCARD)                  |
| `status`       | string | Card status (always ACTIVE for new cards)        |
| `balance`      | number | Current balance transferred from old card        |
| `reference`    | string | Your reference for this operation                |
| `replacedAt`   | string | ISO 8601 timestamp of when the card was replaced |

## Error Responses

| Status | Error Code             | Description                                                  |
| ------ | ---------------------- | ------------------------------------------------------------ |
| 400    | `CARD_TERMINATED`      | Cannot replace a terminated card                             |
| 400    | `INSUFFICIENT_BALANCE` | Business wallet has insufficient balance for replacement fee |
| 404    | `CARD_NOT_FOUND`       | Card not found or doesn't belong to your app                 |
| 500    | `REPLACE_FAILED`       | Failed to replace card at the bank partner                   |

<Tip>
  The `cardId` stays the same after replacement, so you don't need to update your database references. Only the card details (number, expiry, CVV) change.
</Tip>

<Note>
  **Product Fallback**: When replacing a card, the system first tries to issue the same card product type. If that product is no longer available for issuance (i.e., `canIssue: false` in the [products list](/v3/api-reference/cards/products)), the default product (`isDefault: true`) is automatically used instead. The replacement is seamless — the balance is transferred regardless of which product is used.
</Note>

<Note>
  A card replacement fee may apply based on your pricing configuration. Use the [Get Pricing](/v3/api-reference/account/pricing) endpoint to check current fees.
</Note>


## OpenAPI

````yaml v3/openapi.json POST /cards/{cardId}/replace
openapi: 3.1.0
info:
  title: FYATU API v3
  description: >-
    FYATU API v3 with JWT authentication for Collections, Payouts, and Card
    Issuing.
  version: 3.0.0
  contact:
    name: FYATU Support
    url: https://fyatu.com
    email: support@fyatu.com
servers:
  - url: https://api.fyatu.com/api/v3
    description: Production
security: []
tags:
  - name: Authentication
    description: JWT token management endpoints
  - name: Account
    description: Business account, wallet, and address management
  - name: Collections
    description: Accept payments from customers via checkout sessions
  - name: Refunds
    description: Issue refunds for completed collections
  - name: Payouts
    description: Send money to Fyatu account holders
  - name: Cardholders
    description: Cardholder management for card issuing programs
  - name: Cards
    description: Issue, fund, freeze, and manage virtual cards
  - name: Webhooks
    description: Webhook configuration and management
paths:
  /cards/{cardId}/replace:
    post:
      tags:
        - Cards
      summary: Replace Card
      description: >-
        Replace an existing card with a new one. The cardId remains the same but
        the card details (number, expiry, CVV) are replaced with a new card. Any
        remaining balance is transferred to the new card. Use this when a card
        is compromised, lost, or damaged.
      operationId: replaceCard
      parameters:
        - name: cardId
          in: path
          required: true
          schema:
            type: string
          description: The unique card identifier
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplaceCardRequest'
            example:
              reason: Card compromised
              reference: replace-card-abc123
      responses:
        '200':
          description: Card replaced successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReplaceCardResponse'
              example:
                success: true
                status: 200
                message: Card replaced successfully
                data:
                  id: crd_8f3a2b1c4d5e6f7890abcdef12345678
                  cardholderId: ch_abc123def456
                  name: Alice Example
                  last4: '7890'
                  maskedNumber: '****7890'
                  expiryDate: 01/2029
                  brand: MASTERCARD
                  status: ACTIVE
                  balance: 150
                  reference: replace-card-abc123
                  replacedAt: '2026-01-17T10:00:00+00:00'
                meta:
                  requestId: req_a1b2c3d4e5f6
                  timestamp: '2026-01-17T10:00:00+00:00'
        '400':
          description: Card cannot be replaced
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                terminated:
                  summary: Card is terminated
                  value:
                    success: false
                    status: 400
                    message: Cannot replace a terminated card
                    error:
                      code: CARD_TERMINATED
                insufficient_balance:
                  summary: Insufficient balance for replacement fee
                  value:
                    success: false
                    status: 400
                    message: 'Insufficient balance. Required: $2.00, Available: $1.50'
                    error:
                      code: INSUFFICIENT_BALANCE
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          description: Failed to replace card
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                status: 500
                message: Failed to replace card at bank partner
                error:
                  code: REPLACE_FAILED
      security:
        - BearerAuth: []
components:
  schemas:
    ReplaceCardRequest:
      type: object
      properties:
        reason:
          type: string
          maxLength: 255
          description: >-
            Reason for replacing the card (e.g., 'Card compromised', 'Card
            lost', 'Card damaged')
        reference:
          type: string
          maxLength: 100
          description: >-
            Your unique reference for this operation. Defaults to cardId if not
            provided. Returned in webhooks for easy reconciliation.
    ReplaceCardResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        status:
          type: integer
          example: 200
        message:
          type: string
        data:
          type: object
          properties:
            id:
              type: string
              description: The card identifier (unchanged)
            cardholderId:
              type: string
              description: The cardholder identifier
            name:
              type: string
              description: Name on the card
            last4:
              type: string
              description: Last 4 digits of the new card number
            maskedNumber:
              type: string
              description: Masked card number
            expiryDate:
              type: string
              description: New card expiry date (MM/YYYY)
            brand:
              type: string
              enum:
                - VISA
                - MASTERCARD
              description: Card brand
            status:
              type: string
              enum:
                - ACTIVE
              description: Card status
            balance:
              type: number
              description: Current card balance transferred from old card
            reference:
              type: string
              description: Your reference for this operation
            replacedAt:
              type: string
              format: date-time
              description: When the card was replaced
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        status:
          type: integer
          example: 401
        message:
          type: string
          example: Invalid credentials
        error:
          $ref: '#/components/schemas/Error'
        meta:
          $ref: '#/components/schemas/Meta'
    Meta:
      type: object
      properties:
        requestId:
          type: string
          description: Unique request ID for tracking
          example: req_abc123def456
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the response
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code for programmatic handling
          example: AUTH_INVALID_CREDENTIALS
        details:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
          description: Validation error details (for VALIDATION_ERROR)
    ValidationError:
      type: object
      properties:
        field:
          type: string
          description: Field that failed validation
          example: appId
        message:
          type: string
          description: Validation error message
          example: AppId is required
  responses:
    Unauthorized:
      description: Authentication required or token invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            status: 401
            message: Unable to identify business
            error:
              code: AUTH_TOKEN_INVALID
            meta:
              requestId: req_abc123
              timestamp: '2026-01-05T10:30:00+00:00'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            status: 404
            message: Wallet not found
            error:
              code: RESOURCE_NOT_FOUND
            meta:
              requestId: req_abc123
              timestamp: '2026-01-05T10:30:00+00:00'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token obtained from /auth/token

````