Pull API Calls

Businesses who have the pull_payment feature enabled may use the pull API calls. These calls let customers redeem brand cash at a point of sale.

(For most purposes, it is better to let customers send cash rather than pull it from them, so these calls provide access only to brand cash, not national currency. To receive all types of cash, you should accept a payment code from customers.)

List Redeemable Cash

GET /pull/redeemable

List the brand cash someone can redeem at your business. This call is optional; some apps may use POST /pull/redeem directly.

Permission Required:
 

pull_payment

Request Headers:
 
Query Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
  • sender_uid – Required. The UID of the customer (sender).
  • serial_numbers – Optional. A space-delimited list of cash page serial numbers to be sent. This may affect the list of loops to send. Use this when the user has already chosen a specific page or list of pages to send.
Status Codes:
  • 200 OK

    Successful. The response body is a JSON object with these attributes:

    loops
    List of SendableAmount objects. Specifies the types of cash and amounts the user can send to your business, in order from most specific to most general. The app should normally present the loops to the user in the order given by WingCash. If the list is empty, the sender has no cash that your business can redeem.
    sender_info
    A UIDInfo object about the sender. (If the is_individual attribute of sender_info is false, the sender is a business.)
    recipient_info
    A UIDInfo object about your business.
  • 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.

Redeem Cash

POST /pull/redeem

Redeem cash. This API call lets you redeem only brand cash, not open loop cash.

Permission Required:
 

pull_payment

Request Headers:
 
Form Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
  • sender_uid – Required. The UID of the customer.
  • amounts

    Optional. A space-delimited list of loop IDs and amounts to send, formatted as loop_id-currency-amount. For example, to send USD $10.05 of loop 1022 and $0.25 of loop 1023, amounts should be:

    1022-USD-10.05 1023-USD-0.25

    Apps can let WingCash choose loop IDs automatically. To use this feature, replace the loop ID with the string any. When apps specify an abstract amount with any, WingCash sends cash most specific to your business before sending more general cash. For example, to send USD $1.00 of any cash your business can redeem, use the following amounts:

    any-USD-1.00

    Apps can also request specific amounts along with abstract amounts. In the example below, WingCash allocates $0.25 of loop 1023 before allocating another $1.00 of any loop, for a total of $1.25:

    1023-USD-0.25 any-USD-1.00
  • non_wingcash_amount – Optional decimal amount. Specifies how much the customer paid outside WingCash. Provide this information to improve the reports available through WingCash.
  • non_wingcash_currency – Optional. Defaults to USD.
  • serial_numbers – Optional. A space-delimited list of cash page serial numbers to be sent. Use this when the customer has already chosen a specific cash page or list of cash pages to send.
  • private – Optional. Set to true to send the cash privately or false to send publicly. Defaults to true.
  • message – An optional text message to send. WingCash accepts up to 1000 characters.
  • appdata.* – Optional app-specific transfer data, one value per field. Replace the * with field names appropriate for your app. WingCash recommends you use an app-specific field name prefix, so if you choose myapp as a prefix and you want to store a transaction_id field, you should name your field appdata.myapp.transaction_id. All appdata values will be stored in the transfer and reflected in transfer lists and details. You may add a total of up to 10,000 characters (the total number of characters in keys and values) of appdata to a transfer.
Status Codes: