Payment Processor API Calls

Payment processors who have a special arrangement with WingCash may use the payment processor API calls. These API calls let customers redeem brand cash at a point of sale.

These API calls are similar to the Pull API Calls. The difference is that the Pull API calls are designed to be called by a merchant, while these API calls are designed to be called by a third party payment processor acting on behalf of the merchant and customer. The key difference is that these API calls expect a recipient_id parameter that identifies a merchant or an individual.

These calls require an access token. To create the token, first create an app here:

https://wingcash.com/app

Visit the app’s Test tab to create your access token. Grant the offline and process_payment permissions to your access token. Put your access token in your app’s configuration file.

Access tokens granted to payment processors are more valuable than ordinary access tokens, so you must protect your access token. You must not include your access token in any kind of mobile app or desktop app. You must call these functions using a server-side app, not a mobile app or desktop app. Do not install your access token on merchant point of sale equipment. Keep your access token on your own physically protected server. If you lose control of your access token, you must revoke it and create a new token.

List Sendable Cash

GET /proc/sendable

List the brand cash someone can redeem at a merchant location or send to an individual. This call is optional; some apps may use POST /proc/send directly.

This API call was previously named /proc/redeemable. /proc/redeemable is now a deprecated alias.

Permission Required:
 

process_payment.

Request Headers:
 
Query Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
  • sender_id – Required. The profile ID of the sender.
  • recipient_id – Required. The profile ID of the recipient. The recipient must be either a business that accepts the cash for redemption or an individual.
  • 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. Provides the types of cash and amounts the user can send to the specified recipient, 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 the recipient 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 the recipient. (If the is_individual attribute of recipient_info is false, the recipient is a 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.

Send Cash

POST /proc/send

Send cash for redemption at a merchant location or for transfer to an individual. This API call lets you send only brand cash, not open loop cash.

This API call was previously named /proc/redeem. /proc/redeem is now a deprecated alias.

Permission Required:
 

process_payment.

Request Headers:
 
Form Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
  • sender_id – Required. The profile ID of the sender.
  • recipient_id – Required. The profile ID of the recipient. The recipient must be either a business that accepts the cash for redemption or an individual.
  • 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 the recipient before sending more general cash. For example, to send USD $1.00 of any cash accepted by the recipient, 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

    When the amounts parameter is omitted, client apps should provide the non_wingcash_amount instead, to report money sent outside WingCash.

  • 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 user 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: