Cash Design API Calls

Every coin and bill stored in WingCash wallets is derived from a cash design. Each cash design represents either national currency (also known as open loop cash) or brand cash (also known as closed loop cash). Use the cash design API calls to list the cash designs you manage, send cash with your design, and bill customers in exchange for brand cash.

Get Cash Design Information

GET /design

List the cash designs you are allowed to view. Lists only cash designs for which you have been explicitly granted the view_design permission; the list does not include other published cash designs.

The amount of detail available from this API call depends on whether you have the edit_design and view_design_network permissions in addition to the view_design permission. See the CashDesign documentation.

Permission Required:
 

view_design. See Permissions.

Request Headers:
 
Query Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
Status Codes:
GET /design/(string: design_id)

Get information about a cash design you are allowed to view. (Everyone is allowed to view information about published cash designs, and when a cash design is put into circulation, it is automatically published.)

The amount of detail available to your app depends on whether you have the edit_design and view_design_network permissions in addition to the view_design permission. See the CashDesign documentation.

Permission Required:
 

view_design. This permission is granted to everyone (in context of the specific cash design) when the cash design is published. See Permissions.

Request Headers:
 
Query Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
Status Codes:

Create and Send Cash

POST /design/(string: design_id)/send

Create and send cash with a specific design. Available only for brand cash designs (where the type attribute is gl_design).

Permission Required:
 

apply_design. See Permissions.

Request Headers:
 
Request JSON Object:
 
  • recipient_uid (string) – Required. The UID of the recipient. Accepted UID types include wingcash, username, and external UID types such as email, facebook, twitter, and linkedin. The recipient UID type and the sender UID type must match, although username UIDs are resolved internally to wingcash UIDs.
  • distribution_plan_id (string) – Required. The ID of the DistributionPlan to use. The distribution plan must be connected with the specified cash design. The distribution plan specifies who should receive the national currency before and after redemption of the brand cash.
  • amount (string) – Required. The amount to send.
  • sender_uid (string) – Optional. The UID of the sender. Must be listed in the confirmed_uids of the authenticated profile. Defaults to the wingcash_uid of the authenticated profile.
  • message (string) – Optional. The message to send. WingCash accepts up to 1000 characters.
  • private (boolean) – Optional. Set to true to send the cash privately or false to send publicly. Defaults to true.
  • require_recipient_email (boolean) – Optional. If set to true and the recipient has not confirmed their email address, WingCash will send an invitation to the recipient rather than send cash immediately. If this is false (the default), WingCash will send cash to the recipient immediately, even if they have not confirmed their email address.
  • appdata.* (string) – 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.
  • dedup_id (string) – Optional string (up to 128 characters) that helps prevent transfer duplication. Set it to a random string or some hash computed from the transfer parameters and current time. If WingCash receives multiple transfer requests from the same sender, with the same dedup_id, within 24 hours, WingCash will create only one transfer and respond with details about the same transfer to all affected requests. Once dedup_id is set appropriately, you can safely re-transmit the transfer request as needed.
Status Codes:

Bill a Customer

POST /design/(string: design_id)/bill

Bill a customer for a specified amount. When the customer pays, the customer will receive cash of this design. Only WingCash merchants with the bill feature enabled can use this API call. Available only for brand cash designs (where the CashDesign type attribute is gl_design).

WingCash will start a transfer that sends an email to the customer and waits for a payment. WingCash will send daily reminders until the customer confirms the payment is sent. When WingCash receives the payment, the transfer will give the customer brand cash of the specified design to the customer.

The customer or merchant can cancel the transfer at any time before WingCash receives the payment. If the customer fails to pay within 14 days, WingCash will automatically cancel the transfer. Developers should use Webhooks to receive notification of transfers completed, canceled, or updated.

This call requires at least one of the sender_uid or profile_creation_data parameters. If sender_uid is provided and WingCash can find a wallet with the specified sender_uid, the profile_creation_data will be ignored. Otherwise, WingCash will use the profile_creation_data to create a new individual profile.

The bill API call and bill transfer workflow are a little unusual in that the merchant, who is the transfer recipient, initiates the transfer, while the customer is the sender. Most other transfers are initiated by the sender. Bill transfers are structured this way because, in a bill transfer, the first transfer of money is from the customer.

Permission Required:
 

apply_design. See Permissions.

Request Headers:
 
Request JSON Object:
 
  • amount (string) – Required. Specifies both the amount to bill the customer and the amount of brand cash to send upon receipt of payment.
  • distribution_plan_id (string) – Required. The ID of the distribution plan to use. The distribution plan must be connected with the specified cash design. The distribution plan specifies who should receive the national currency before and after redemption of the brand cash.
  • sender_uid (string) – Optional. The UID of the customer who is to send the payment. At least one of sender_uid or profile_creation_data is required. Accepted UID types include wingcash, username, and external UID types such as email, facebook, twitter, and linkedin.
  • profile_creation_data (object) – Optional. A ProfileCreationData object that provides the information for creating a customer profile.
  • message (string) – Optional. The message to send. WingCash accepts up to 1000 characters.
  • private (boolean) – Optional. Set to true to send the cash privately or false to send publicly. Defaults to true.
  • appdata.* (string) – 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.
  • dedup_id (string) – Optional string (up to 128 characters) that helps prevent transfer duplication. Set it to a random string or some hash computed from the transfer parameters and current time. If WingCash receives multiple transfer requests from the same sender, with the same dedup_id, within 24 hours, WingCash will create only one transfer and respond with details about the same transfer to all affected requests. Once dedup_id is set appropriately, you can safely re-transmit the transfer request as needed.
Status Codes:
  • 200 OK – Successful. The response body is a TransferDetail JSON object with bill transfer details.
  • 401 Unauthorized – The access token is missing, not valid, or the hard expiration has passed. See Unauthorized Response.
  • 403 Forbidden – The access token is valid, but the app is not authorized to access either this function or the cash design specified.
  • 404 Not Found – The specified cash design could not be found.

Add a Network Membership Agreement

POST /design/(string: design_id)/agreement/add

Add a member to the network for a cash design. You must specify the terms of membership, and to complete the agreement, the member must agree to the terms you specified. Each member must have at least one role:

  • Redeemer. Redeemers accept the cash as payment for goods and services.
  • Distributor. Distributors are permitted to issue the cash and send it to customers.
  • Settler. Settlers must provide the national currency to pay for distribution and redemption.

The agreement is initially in the inactive state, waiting for the member to activate the agreement. (Note: when adding an agreement for your own profile, the agreement is automatically activated.)

Permission Required:
 

add_agreement. See Permissions.

Request Headers:
 
Request JSON Object:
 
  • uid (string) – Required. The UID of the member to add.
  • redeemer (boolean) – Optional. Set to true to add the member as a redeemer.
  • distributor (boolean) – Optional. Set to true to add the member as a distributor.
  • settler (boolean) – Optional. Set to true to add the member as a settler.
  • terms_text (string) – Required. A short description of the terms of the agreement between the member and the cash network. Up to 50 characters.
  • terms_link (string) – Optional. The URL of a document containing the full terms of the agreement between the member and the cash network. The document may be hosted by various services such as Dropbox, Google Docs, DocuSign, etc.
Status Codes:

Activate a Network Membership Agreement

POST /design/(string: design_id)/agreement/(string: agreement_id)/activate

Activate a cash network member agreement. Inactive agreements can only be activated by the member specified in the agreement.

Warning

Using this API call has legal implications. Agreements must not be activated until the member formally agrees to the terms of membership in the cash network.

Permission Required:
 

activate_agreement. See Permissions.

Request Headers:
 
Status Codes:

Deactivate a Network Membership Agreement

POST /design/(string: design_id)/agreement/(string: agreement_id)/deactivate

Deactivate an agreement. Either the owners of a cash network or the connected member can deactivate a cash network member agreement.

Permission Required:
 

deactivate_agreement. See Permissions.

Request Headers:
 
Status Codes:

Remove Network Membership Agreements

POST /design/(string: design_id)/agreement/remove

Remove network agreements. Returns the updated list of network agreements.

Note

If you try to remove agreements that you are not permitted to remove, this API call will not remove them and will not generate a permission error.

Permission Required:
 

remove_agreement. See Permissions.

Request Headers:
 
Request JSON Object:
 
  • ids (list) – Required. The list of agreement IDs to remove.
Status Codes:
  • 200 OK – Successful. The response body is a list of CashDesignAgreement JSON objects. The list is filtered if you are not permitted to see the whole network.
  • 401 Unauthorized – The access token is missing, not valid, or the hard expiration has passed. See Unauthorized Response.
  • 403 Forbidden – The access token is valid, but the app is not authorized to access either this function or the cash design specified.
  • 404 Not Found – The specified cash design could not be found.