> ## Documentation Index > Fetch the complete documentation index at: https://docs.loyalty.dog/llms.txt > Use this file to discover all available pages before exploring further. # Transfergiftcardbalance > ### 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 ## OpenAPI ````yaml https://api.loyalty.dog/openapi.json post /v2/giftcards/programs/{programId}/cards/{cardId}/transfer openapi: 3.1.0 info: title: LoyaltyDog description: >- Welcome to the LoyaltyDog API! This API provides access to our loyalty program features, allowing you to integrate with various platforms and manage your loyalty data. Want to query LoyaltyDog via an AI assistant (Claude, Cursor, Windsurf)? See the [MCP Integration guide](https://loyaltydog.ai/playground#mcp). termsOfService: https://loyalty.dog/loyalty-program-terms-service contact: name: LoyaltyDog Support url: https://loyalty.dog/contact-us email: support@loyalty.dog version: 1.0.1 servers: - url: https://api.loyalty.dog description: Production security: - bearerAuth: [] paths: /v2/giftcards/programs/{programId}/cards/{cardId}/transfer: post: tags: - Gift Cards summary: Transfergiftcardbalance description: >- ### 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 operationId: >- transferGiftCardBalance_v2_giftcards_programs__programId__cards__cardId__transfer_post parameters: - name: programId in: path required: true schema: anyOf: - $ref: '#/components/schemas/PydanticObjectId' - type: 'null' title: Programid - name: cardId in: path required: true schema: anyOf: - $ref: '#/components/schemas/PydanticObjectId' - type: 'null' title: Cardid - name: idempotency-key in: header required: false schema: anyOf: - type: string - type: 'null' title: Idempotency-Key - name: X-Eposn-Customer-Token in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Eposn-Customer-Token - name: X-Eposn-Merchant-Token in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Eposn-Merchant-Token requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TransferBalanceRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TransferBalanceResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: PydanticObjectId: type: string maxLength: 24 minLength: 24 pattern: ^[0-9a-f]{24}$ example: 5eb7cf5a86d9755df3a6c593 TransferBalanceRequest: properties: securityCode: type: string maxLength: 6 minLength: 6 title: Securitycode destinationCardNumber: type: string maxLength: 20 title: Destinationcardnumber amount: anyOf: - type: number maximum: 5000 minimum: 0.01 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Amount description: anyOf: - type: string maxLength: 500 - type: 'null' title: Description referenceId: anyOf: - type: string maxLength: 100 - type: 'null' title: Referenceid type: object required: - securityCode - destinationCardNumber - amount title: TransferBalanceRequest TransferBalanceResponse: properties: success: type: boolean title: Success message: type: string title: Message transferId: type: string title: Transferid sourceCard: $ref: '#/components/schemas/TransferBalanceSourceCard' destinationCard: $ref: '#/components/schemas/TransferBalanceDestCard' amountTransferred: type: string title: Amounttransferred type: object required: - success - message - transferId - sourceCard - destinationCard - amountTransferred title: TransferBalanceResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError TransferBalanceSourceCard: properties: id: $ref: '#/components/schemas/PydanticObjectId' cardNumber: type: string title: Cardnumber remainingBalance: type: string title: Remainingbalance status: $ref: '#/components/schemas/GiftCardStatus' type: object required: - id - cardNumber - remainingBalance - status title: TransferBalanceSourceCard TransferBalanceDestCard: properties: id: $ref: '#/components/schemas/PydanticObjectId' cardNumber: type: string title: Cardnumber newBalance: type: string title: Newbalance type: object required: - id - cardNumber - newBalance title: TransferBalanceDestCard ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError GiftCardStatus: type: string enum: - pending - active - suspended - expired - voided - depleted title: GiftCardStatus description: Gift card status enumeration. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT access token obtained from POST /v2/token. ````