Report API Calls

Received and Receivable

POST /wallet/report/receivable

Generate a list of payments received and receivable by the authenticated profile. The main purpose of the report is to show merchants what open loop cash has been or will be received as a result of accepting closed loop payments.

In this report, because a payment may be funded by multiple types of cash, a payment often spans multiple redemption rows. When presenting the report to users, you should consider grouping rows by transfer_id (or other fields) for clarity.

Permission Required:
 

view_history. See Permissions.

Request Headers:
 
Request JSON Object:
 
  • version (string) – Optional. If provided, must be 1.
  • access_token (string) – Optional alternative to the Authorization Header.
  • start_date (string) – Optional. Limit the results to transfers on the start_date or later. Format: YYYY-MM-DD.
  • end_date (string) – Optional. Limit the results to transfers on the end_date or before. Format: YYYY-MM-DD.
  • pos_device (string) –

    Optional. Limit the results to payments received by specific point of sale devices. The valid values are:

    • any_or_none (default): Include payments from any point of sale device and payments received directly (with no point of sale.)
    • any: Include payments from any point of device, but not payments received directly.
    • none: Include payments received directly, but not payments received from a point of sale device.
    • <profile_id>.<device_id>: Include only payments received from a specific point of sale. Provide the profile ID and the device ID. (The report includes profile and device IDs.)
  • settlement_types (list) –

    Optional list of strings. Limit the results to payments matching any of the specified settlement types. The current valid settlement types are:

    • init_dist: A payment received as a result of cash distribution before redemption.
    • redeem: A payment received as a result of redeeming closed loop cash.
    • immediate: An immediate payment of open loop cash.
    • paycard: Funds received through payment card settlement.
    • non_wingcash: A payment received outside WingCash. This information is only available if the merchant tells WingCash how much money was received outside WingCash at the time of payment.
  • csv (bool) – Optional. If true, this API call will generate a CSV (Comma Separated Value) report rather than JSON.
Status Codes:
  • 200 OK

    Successful. If the csv parameter is true, the response body is a CSV document containing redemption rows. Otherwise, the response body is a JSON object with these attributes:

    • report_type
      Contains the string received_and_receivable.
    • generated_timestamp
      The ISO 8601 timestamp when the report was generated.
    • generated_by
      An object containing the id, title, personal_id, and personal_title of the profile that generated the report.
    • filters
      An object that echoes the start_date, end_date, pos_device, and settlement_types provided in the parameters.
    • report
      A list of redemption row objects. Each row contains:
      • date
        String: the date of the redemption.
      • timestamp
        String: the ISO 8601 timestamp of the redemption.
      • transfer_id
        String: the WingCash transfer ID of the redemption.
      • pos_device_holder_id
        String: the profile ID of the owner of the point of sale device that received the payment.
      • pos_device_id
        String: the ID of the point of sale device. Device IDs are specific to profile IDs.
      • dist_tid
        String: the WingCash transfer ID of the purchase (distribution) of the closed loop cash that was redeemed. WingCash keeps track of the distribution transfer ID until the closed loop cash is redeemed. (The distribution plan contained in the distribution transfer determines settlement before and after redemption.)
      • settlement_type
        String: the type of settlement. See the settlement_types field above for a list of valid values.
      • received_currency
        String: the code of the currency that was received.
      • settle_currency
        String: the code of the currency for settlement of this redemption.
      • loop_id
        String: the ID of the redeemed cash design.
      • is_fundable
        Boolean: true if this redemption resulted in either immediate or deferred settlement; false if the distribution plan specified that no funds will be received.
      • tender_type
        String: describes how the payment was received. Valid values include wingcash, paycard, physical, and non_wingcash. More tender types may be added later.
      • received_amount
        String containing a decimal value: the amount redeemed in received_currency units.
      • settle_funded
        String containing a decimal value: this field states, in settle_currency units, how much is to be settled or has been settled as a result of this redemption. If the redemption is not fundable, this field contains 0.
      • settle_reclaimed
        String containing a decimal value: this field states, in settle_currency units, how much of the settlement was canceled by payment card chargebacks (or other methods of canceling payments).
      • settle_pending
        String containing a decimal value: this field states, in settle_currency units, how much of the settlement has not yet been received by the merchant.
      • settle_settled
        String containing a decimal value: this field states, in settle_currency units, how much of the settlement has been received by the merchant.
  • 400 Bad Request – The parameters are not valid. The response body contains an InvalidRequest object.
  • 401 Unauthorized – The access token is missing or not valid. See Unauthorized Response.
  • 403 Forbidden – The access token is valid but the app is not authorized to access this function.