Search

Are you looking for test card numbers?

Would you like to contact support?

Payment-method icon

Merge the balance of two gift cards

Learn how to transfer the value from one stored-value card to another one of the same type.

With a /mergeBalance call to our Stored Value API, you can transfer the full value of a gift card or other type of stored-value card to another one. The source and target card need to be of the same type. For example, two ValueLink gift cards.

Support

Web channel

Transaction Givex SVS ValueLink
Merge balance -x- -x- -white_check_mark-

POS channel

Transaction Givex SVS ValueLink
Merge balance -x- -x- -white_check_mark-

Merge the balance

To transfer the full value from the 'source' gift card to the 'target' one:

  • Make a POST request to the https://pal-test.adyen.com/pal/servlet/StoredValue/v46/mergeBalance endpoint, specifying:

    • merchantAccount: ID of the merchant account that you want to process the transaction with.
    • store: Optional For transactions flagged as in-store, the ID of the physical store that you want to process the transaction for. Maximum length: 16 characters.
    • Details of the source card that the balance needs to be transferred from. Don't specify a type for the source, because that will be inferred from the target. Use the following fields:

      • sourcePaymentMethod.number: Card number that identifies the card that you want to transfer the value from.
      • sourcePaymentMethod.securityCode: Conditional If the source card has a PIN code or other type of security code, obtain it from the shopper and provide it here.
      • sourcePaymentMethod.expiryMonth: Optional Expiry month of the source card.
      • sourcePaymentMethod.expiryYear: Optional Expiry year of the source card.
      • sourcePaymentMethod.holderName: Optional Name of the shopper that the source card belongs to.

    • paymentMethod.type: Name or brand of the card. Accepted values: valuelink.

    • Details of the target card that the balance needs to be transferred to. If you tokenized a payment that the shopper made with this card, you can use the token and shopper reference. Otherwise, use fields inside the paymentMethod object.

      Without token:
      To provide target payment method details when you don't have a token, specify:

      • paymentMethod.number: Card number that identifies the target card that you want transfer funds to.
      • paymentMethod.securityCode: Conditional If the target card has a PIN code or other type of security code, obtain it from the shopper and provide it here.
      • paymentMethod.expiryMonth: Optional Expiry month of the target card.
      • paymentMethod.expiryYear: Optional Expiry year of the target card.
      • paymentMethod.holderName: Optional Name of the shopper that the target card belongs to.

      With token:
      To provide target payment method details using a token you created earlier, specify:

      • recurringDetailReference: The token. This is the recurringDetailReference returned in the response when you tokenized a payment that was made with the target card.
      • shopperReference: Your unique ID for this shopper. This is the shopperReference that you used when you created the token.
      • shopperInteraction: Specifies the sales channel through which the shopper provided their details. Accepted values: Ecommerce (default for online transactions), ContAuth (online, using previously stored details), Moto (via email or telephone) or POS (using an in-store terminal).

    • reference: Your reference to uniquely identify the transaction. To provide multiple references for a transaction, separate them with hyphens ("-"). Maximum length: 80 characters.

    This request transfers the balance of card no. 7777182708544835 to card no. 8888182708544836:

    {
        "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
        "store":"YOUR_STORE_ID",
        "sourcePaymentMethod": {
            "number": "7777182708544835",
            "securityCode": "2329"
        },            
        "paymentMethod": {
            "type": "valuelink",
            "number": "8888182708544836",
            "securityCode": "2330"
        },
        "reference": "YOUR_REFERENCE"
    }

Response

You receive a response containing:

  • currentBalance: The currency and total value in minor units of the funds stored on the card.
  • pspReference: Adyen's 16-character unique reference associated with the request.
  • resultCode: Indicates the state of the request. Refer to Result codes for the values that you can receive.

The response may include additional fields, depending on the Additional data settings for your merchant account. In the Customer Area, you'll find these settings under Account > API URLs.

Sample response:

{
    "currentBalance": {
        "currency": "EUR",
        "value": 5600
    },
    "pspReference": "881564657480267D",
    "resultCode": "Success"
}

Next steps

See also