---
title: "Transfergiftcardbalance"
method: POST
path: "/v2/giftcards/programs/{programId}/cards/{cardId}/transfer"
tags: ["Gift Cards"]
---

# Transfergiftcardbalance

`POST /v2/giftcards/programs/{programId}/cards/{cardId}/transfer`

### Transfer Balance Between Gift Cards

Moves a specified amount from a source gift card to a destination gift card within the same program.
The source card's security code is required to authorise the transfer.

Both cards must be active and belong to the same program. A `TRANSFER_OUT` transaction is recorded
on the source card and a `TRANSFER_IN` transaction on the destination card.

**Business Rules**:
- Source and destination cards must be different
- Both cards must have status `active`
- Source card balance must be >= transfer amount
- Destination card balance after transfer must not exceed £10,000.00
- Source card security code must match (constant-time comparison)
- Transfer depletes source card if resulting balance reaches zero

**Status Codes**:
- 200: Transfer completed successfully
- 400: Invalid amount, insufficient balance, or cards not eligible
- 401: Incorrect security code
- 404: Source or destination card not found
- 409: Card currently locked by another operation

**Idempotency Scope**:
- Idempotency keys are scoped to `programId + transfer + sourceCardId + destinationCardId`
- The same key may be reused for different source/destination pairs or other gift card actions

## Path parameters

- `programId` string, required
- `cardId` string, required

## Headers

- `idempotency-key` string, nullable
- `X-Eposn-Customer-Token` string, nullable
- `X-Eposn-Merchant-Token` string, nullable

## Request body

- TransferBalanceRequest
  - `securityCode` string, required
  - `destinationCardNumber` string, required
  - `amount` union, required
    - number
    - string
  - `description` string, nullable
  - `referenceId` string, nullable

## Response `200`

Successful Response

- TransferBalanceResponse
  - `success` boolean, required
  - `message` string, required
  - `transferId` string, required
  - `sourceCard` TransferBalanceSourceCard, required
    - `id` string, required
    - `cardNumber` string, required
    - `remainingBalance` string, required
    - `status` 'pending' | 'active' | 'suspended' | 'expired' | 'voided' | 'depleted', required — Gift card status enumeration.
  - `destinationCard` TransferBalanceDestCard, required
    - `id` string, required
    - `cardNumber` string, required
    - `newBalance` string, required
  - `amountTransferred` string, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/loyalty/apis/loyaltydog.md) · [All operations](https://skmtc.net/loyalty/apis/loyaltydog/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/loyalty/loyaltydog/versions/42b7b22af2b6/schema)