Balance Transfer Service
========================

The balance transfer service provides endpoints to request the transfer of wallet balances from one card to another.

.. contents:: Topics

Endpoints
---------

Transfer Balances
~~~~~~~~~~~~~~~~~

.. http:post:: balancetransfer/transferBalances.json

   Transfer balances from one specified card (account) to another. Authentication will be performed against the account corresponding to the printedCardNumber.

   The following authentication methods are allowed for this endpoint:

   * :ref:`b2b_auth`
   * :ref:`oauth_auth`

   :jsonparam Integer merchantId: *(required)*  Paytronix-assigned merchant identifier (ID) in which to perform the operation.
   :jsonparam String printedCardNumber: *(required)*  Printed card number associated with the account/user requesting the transfer of balances (to this card)
   :jsonparam String fromPrintedCardNumber: *(required)*  Printed card number associated with the account from which to transfer balances
   :jsonparam Boolean mustTransferAllWallets: *(optional)*  Specifies if the transaction should fail if not all wallet balances can be transferred to the receiving card
   :jsonparam String fromRegCode: *(optional)*  Reg code of the printed card number associated with the account from which to transfer balances

.. http:response:: success

   :jsonparam String result: *(required)*  ``success``

.. http:response:: failure

   :jsonparam String result: *(required)*  ``failure``
   :jsonparam String errorCode: *(required)*  The error code of the failure.
   :jsonparam String errorMessage: *(required)*  The human readable error message of the failure.

Error Codes
-----------

The following are the possible codes and messages that can be returned by the Balance Transfer Service.

There are other system-level errors which may be returned which are not documented here.

The caller of the endpoint can use the returned message to display to the end user or, if different wording is desired, can provide their own mapping of code to message.

+---------------------------------------------------+-------------------------------------------------------------------------------+
| Code                                              | Message                                                                       |
+===================================================+===============================================================================+
| ``balancetransfer.error``                         | System error                                                                  |
+---------------------------------------------------+-------------------------------------------------------------------------------+
| ``balancetransfer.invalid_from_card``             | 'From' card number is invalid                                                 |
+---------------------------------------------------+-------------------------------------------------------------------------------+
| ``balancetransfer.invalid_to_card``               | 'To' card number is invalid                                                   |
+---------------------------------------------------+-------------------------------------------------------------------------------+
| ``balancetransfer.inactive_from_account``         | 'From' account must be active                                                 |
+---------------------------------------------------+-------------------------------------------------------------------------------+
| ``balancetransfer.inactive_from_card``            | 'From' card must be active                                                    |
+---------------------------------------------------+-------------------------------------------------------------------------------+
| ``balancetransfer.registered_from_card``          | 'From' card must not be registered                                            |
+---------------------------------------------------+-------------------------------------------------------------------------------+
| ``balancetransfer.inactive_to_account``           | 'To' account must be active                                                   |
+---------------------------------------------------+-------------------------------------------------------------------------------+
| ``balancetransfer.inactive_to_card``              | 'To' card must be active                                                      |
+---------------------------------------------------+-------------------------------------------------------------------------------+
| ``balancetransfer.no_transferable_balances``      | No balances can be transferred between cards                                  |
+---------------------------------------------------+-------------------------------------------------------------------------------+
| ``balancetransfer.all_balances_not_transferable`` | Caller requested all balances transfer but not all balances are transferable  |
+---------------------------------------------------+-------------------------------------------------------------------------------+