Gift Transfer Service ===================== .. contents:: Topics General Lifecycle ~~~~~~~~~~~~~~~~~~ .. image:: gift_transfer_flow.png :align: center Endpoints ~~~~~~~~~~ Transfer Out ------------ .. http:post:: gifttransfer/transferOut.json Transfer some balance out of a source account identified by printed card number to some destination The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID in which to perform the operation :jsonparam String fromPrintedCardNumber: *(required)* Primary card number of the account the transfer is coming from :jsonparam Object to: *(required)* Account the transfer is intended for, either :http:jsonentity:`TransferToAccount` or :http:jsonentity:`TransferToExternal` :jsonparam Integer walletCode: *(required)* A numeric identifier for a specific type of reward, unique for a given merchant :jsonparam String transferMessage: Optional message to be included with transfer .. http:response:: success Indicates that the operation succeeded :jsonparam String result: *(required)* ``success`` :jsonparam Object transferInfo: *(required)* See :http:jsonentity:`TransferInfo` for format of the object .. http:response:: failure Indicates that the operation did not complete successfully, and any adjustments were rolled back as best as possible (if necessary). :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 Get Gifting Configuration ------------------------- .. http:get:: gifttransfer/giftingConfig.json Fetch a list of all rewards for this merchant, integration, and card that are available for a guest to transfer as a gift The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID in which to perform the operation :query Integer cardTemplateCode: *(required)* Paytronix-assigned card template code identifying the card type of the guest .. http:response:: success Indicates that the operation succeeded :jsonparam String result: *(required)* ``success`` :jsonparam List[Object] configs: *(required)* See :http:jsonentity:`GiftingConfig` for format of the object .. http:response:: failure Indicates that the operation did not complete successfully, and any adjustments were rolled back as best as possible (if necessary). :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 Accept Transfer In ------------------ .. http:post:: gifttransfer/acceptTransferIn.json Accept a pending inbound transfer. .. note:: The transfer must be destined for the particular account accepting it. If the transfer was to an external target, the account must have an external account matching the target of the transfer. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID in which to perform the operation in. :jsonparam String code: *(required)* Unique code identifying the transfer from response body of :http:jsonentity:`TransferInfo` :jsonparam String acceptingPrintedCardNumber: *(required)* Primary card number of the account the transfer is going to :jsonparam String message: Optional message to be included with transfer .. http:response:: success Indicates that the operation succeeded :jsonparam String result: *(required)* ``success`` :jsonparam Object transferInfo: *(required)* See :http:jsonentity:`TransferInfo` for format of the object .. http:response:: failure Indicates that the operation did not complete successfully, and any adjustments were rolled back as best as possible (if necessary). :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 Reject Transfer In ------------------ .. http:post:: gifttransfer/rejectTransferIn.json Reject a pending inbound transfer .. note:: The transfer must be destined for the particular account accepting it. If the transfer was to an external target, the account must have an external account matching the target of the transfer. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID in which to perform the operation in :jsonparam String code: *(required)* Unique code identifying the transfer being rejected :jsonparam String rejectingPrintedCardNumber: Primary card number of the account for which the transfer is being rejected :jsonparam String message: Optional message to be included with rejected transfer .. http:response:: success Indicates that the operation succeeded :jsonparam String result: *(required)* ``success`` :jsonparam Object transferInfo: *(required)* See :http:jsonentity:`TransferInfo` for format of the object .. http:response:: failure Indicates that the operation did not complete successfully, and any adjustments were rolled back as best as possible (if necessary). :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 Fetch Pending Transfer ---------------------- .. http:get:: gifttransfer/pendingTransfer.json Fetch information about a pending transfer The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID in which to perform the operation in. :query String code: *(required)* Unique code identifying the pending transfer .. http:response:: success Indicates that the operation succeeded :jsonparam String result: *(required)* ``success`` :jsonparam Object transferInfo: *(required)* See :http:jsonentity:`TransferInfo` for format of the object .. http:response:: failure Indicates that the operation did not complete successfully, and any adjustments were rolled back as best as possible (if necessary). :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 Fetch Pending Transfers To Account ---------------------------------- .. http:get:: gifttransfer/pendingTransfersToAccount.json Enumerate any pending transfers for an account identified by printed card number that are destined for either the particular account by ID or to any of the account's linked external accounts The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID in which to perform the operation in. :query String printedCardNumber: *(required)* The card of the guest. .. http:response:: success Indicates that the operation succeeded :jsonparam String result: *(required)* ``success`` :jsonparam List[Object] transferInfo: *(required)* List of any pending transfers for an account, see :http:jsonentity:`TransferInfo` for format of the object .. http:response:: failure Indicates that the operation did not complete successfully, and any adjustments were rolled back as best as possible (if necessary). :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 Fetch Transfer History For Account ---------------------------------- .. http:get:: gifttransfer/transferHistoryForAccount.json Enumerate all transfer activity related to a particular account for viewing a history of transfers .. note:: Fetches all transfers transferred out of the given account, regardless of status, plus all transfers transferred into the given account, as long as they aren't in the pending state The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID in which to perform the operation in. :query String printedCardNumber: *(required)* The card of the guest. .. http:response:: success Indicates that the operation succeeded :jsonparam String result: *(required)* ``success`` :jsonparam List[Object] transferInfo: *(required)* List of any transfers for an account, see :http:jsonentity:`TransferInfo` for format of the object .. http:response:: failure Indicates that the operation did not complete successfully, and any adjustments were rolled back as best as possible (if necessary). :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 Request Objects --------------- .. http:jsonentity:: TransferToAccount Information about the Paytronix account the transfer is intended for :jsonparam Long accountCode: *(required)* Unique account code of account transfer is intended for .. http:jsonentity:: TransferToExternal Information about the external account the transfer is intended for :jsonparam String identifier: *(required)* String identifying the external account to transfer to, either FacebookID or email address :jsonparam String name: *(required)* Name of the person the gift transfer is intended for Reply Objects ------------- .. http:jsonentity:: TransferInfo Information about a successful transfer transaction :jsonparam Boolean inbound: *(required)* Indicates whether the transfer is inbound (``true``) or outbound (``false``) :jsonparam String status: *(required)* One of ``"PENDING"``, ``"ACCEPTED"``, ``"REJECTED"``, ``"RETURNED"``, or ``"EXPIRED"`` :jsonparam String fromPrintedCardNumber: *(required)* Primary card number of the account the transfer is coming from :jsonparam Object fromUserInformation: *(required)* Limited set of UserFields including: salutation, first name, last name :jsonparam String toPrintedCardNumber: Primary card number of the account the transfer is intended for :jsonparam Object toUserInformation: Limited set of UserFields :jsonparam Object externalTarget: See :http:jsonentity:`TransferTargetExternal` for format of the object :jsonparam Object balance: *(required)* See :http:jsonentity:`TransferredBalance` for format of the object :jsonparam Long transferOutTransactionId: *(required)* Unique identifier of the outbound transaction :jsonparam Long transferInTransactionId: Unique identifier of the inbound transaction :jsonparam Long voidTransferOutTransactionId: Unique identifier of the voided outbound transaction :jsonparam DateTime transferDatetime: *(required)* Date and time at which the transfer occurred in the format ``yyyy-MM-dd HH:mm:ss Z``, ex: ``2012-05-23 16:29:22 -0400`` :jsonparam String transferMessage: Message associated with the transfer :jsonparam DateTime responseDatetime: Date and time of the transfer response in the format ``yyyy-MM-dd HH:mm:ss Z``, ex: ``2012-05-23 16:29:22 -0400`` :jsonparam String responseMessage: Message associated with the response message to transfer :jsonparam Integer transferExpirationDays: Number of days until the transfer expires :jsonparam String externalTargetLink: If transferring to an external account, the link of the target external account .. http:jsonentity:: GiftingConfig Information about a gift (reward) available to transfer :jsonparam String descriptiveLabel: *(required)* The name of the reward :jsonparam Integer walletCode: *(required)* A numeric identifier for a specific type of discount, unique for a given merchant :jsonparam Decimal quantityRequired: *(required)* Number of rewards points required for guest to make transfer of this reward .. http:jsonentity:: TransferTargetExternal Information to identify the external account a transfer is intended for :jsonparam Object integration: *(required)* See :http:jsonentity:`IntegrationNames` for format of the object :jsonparam String identifier: *(required)* String identifying the external account to transfer to, typically a FacebookID or email address :jsonparam String name: *(required)* Name of the person the gift transfer is intended for .. http:jsonentity:: IntegrationNames Additional Information about the integration associated with the external account a transfer is intended for :jsonparam String identifier: *(required)* Unique code identifying the integration :jsonparam String name: *(required)* Informal name of the integration :jsonparam String reportingName: *(required)* Reporting name of the integration :jsonparam String detail: Optional detail identifying the integration .. http:jsonentity:: TransferredBalance Information about the reward being transferred :jsonparam Integer sourceWalletCode: *(required)* A numeric identifier for a specific type of reward, unique for a given merchant from the account the tranfer is sent from :jsonparam String sourceWalletName: *(required)* Informal name attributed to the ``sourceWalletCode`` :jsonparam Decimal sourceAmount: *(required)* Amount being transferred out of source account :jsonparam Integer destinationWalletCode: *(required)* A numeric identifier for a specific type of reward, unique for a given merchant for the account the tranfer is intended for :jsonparam String destinationWalletName: *(required)* Informal name attributed to the ``destinationWalletCode`` :jsonparam String destinationWalletPluralName: *(required)* Flural form of informal name attributed to the ``destinationWalletCode`` :jsonparam Decimal destinationAmount: *(required)* Amount being transferred into destination account :jsonparam Date expirationDate: Date that the transfer will expire in the format ``yyyy-mm-dd`` :jsonparam Integer expirationDays: Number of days until expiration :jsonparam String destinationWalletNameTiny: Tiny version of ``destinationWalletName`` :jsonparam String destinationWalletNameShort: Short version of ``destinationWalletName`` :jsonparam String destinationWalletNameLong: Long version of ``destinationWalletName``