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 (open loop cash) or brand cash (closed loop cash). Use the cash design API calls to programmatically create and edit cash designs, list the cash designs you manage, send cash with your design, and bill customers in exchange for brand cash.

Create a Cash Design

POST /design/create
Create a cash design. The new design initially has no image, so after creation, your app should immediately set the image using PUT /design/(string:design_id)/image.
Permission Required

create_design. See Permissions.

Request Headers
Request JSON Object
  • title (string) – Required. The name of the cash design.
  • currency (string) – Required string. An ISO 4217 currency (3 uppercase letters).
  • design_type (string) –

    Required. Available choices:

    gl_design
    Closed loop cash, also known as brand cash or gift and loyalty (GL) cash. Available only to profiles with the design_gl feature.
    open_design
    Open loop cash. Available only to profiles authorized to issue open loop cash (national currency.)
    overlay_design
    An overlay on top of open loop cash. Available to all profiles. WingCash charges for the application of the overlay to specific notes.
Status Codes

Set the Default Cash Design Image

PUT /design/(string: design_id)/image

Set or replace the default image for the cash design. Provide a PNG, JPEG, or GIF file as the body of the request. The image will be fit automatically into various rectangles with an aspect ratio close to 16:9. The image should be at least 540 pixels wide.

The default cash design image is used when multiple_images is disabled. When multiple_images is enabled, the default image is used as the image for denominations that have not been customized. (See PUT /design/(string:design_id)/image/(string:denomination).)

If you use curl to call this API, use the -T option with a filename to provide the request body.

Permission Required

edit_design. See Permissions.

Request Headers
Status Codes

Set a Denomination-Specific Cash Design Image

PUT /design/(string: design_id)/image/(string: denomination)

Set or replace a denomination-specific image for the cash design. Provide a PNG, JPEG, or GIF file as the body of the request. WingCash uses denomination-specific images only when the multiple_images option is enabled for the design.

The denomination is a decimal string such as 0.01, 0.25, 1, or 100.00.

Permission Required

edit_design. See Permissions.

Request Headers
Status Codes

List Cash Designs

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

Retrieve a Cash Design

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

Edit a Cash Design

PATCH /design/(string: design_id)

Edit a cash design. All fields are optional. To leave an attribute unchanged, exclude the attribute from the request.

Permission Required

edit_design. See Permissions.

Request Headers
Request JSON Object
  • title (string) – Optional. The name of the cash design.
  • description_html (string) – Optional. A description of the cash design in HTML format. The HTML will be stripped of everything but basic tags like <p>, <strong>, <em>, <ul>, <ol>, and <li>. Most tag attributes are also stripped, including style attributes. Links (using <a href="...">) are permitted. Max 10000 characters. To clear this setting, provide a value of null or an empty string.
  • multiple_images (bool) – Optional. True if the cash design should use a different image for each denomination. See PUT /design/(string:design_id)/image/(string:denomination).
  • waves (bool) – Optional. True if WingCash should draw the standard wavy lines over the images.
  • transferable (bool) – Optional. True if WingCash should allow holders of cash with this design to send the cash to other members without redeeming cash.
  • max_per_wallet (string) – Optional string containing a decimal amount. The maximum amount of cash with this design that WingCash should allow any particular member to hold or redeem at once. To clear this setting, provide a value of null or an empty string.
  • designer_id (string) – Optional. Specify the WingCash profile of the person or business who designed the cash design. To clear this setting, provide a value of null or an empty string.
  • featured_id (string) – Optional. Specify the WingCash profile of the business to feature in wallets holding cash of this design. To clear this setting, provide a value of null or an empty string.
  • expire (object) –

    Optional. A JSON object containing the expiration rule for this design. The expiration object has these attributes:

    mode
    null, “absolute”, or “relative”. null means the cash never expires. “absolute” means cash of this design will expire on a specific date and time. “relative” means cash of this design will expire in a certain number of days after purchase.
    absolute
    The ISO 8601 date and time when the cash will expire.
    relative
    Integer; the number of days after purchase when the cash will expire.
  • email_freq (string) –

    Optional. Specifies how often WingCash will remind holders of cash of this design that they hold the cash. The possible values are:

    • daily
    • weekly (Every Monday)
    • weekly2 (Every Monday and Thursday)
    • monthly (First day of every month)
    • null (never, except the last 7 days before expiration)
  • generic_provider (bool) – Optional. If true, cash pages with this design should show WingCash as the provider. If false, cash pages with this design should show the WingCash profile identified by issuer_id as the provider.
  • icon (object) –

    Optional. Provide an object containing:

    media_id
    String: a media identifier returned by PUT /design/(string:design_id)/icon for the same design. To clear the icon, provide a value of null or an empty string.
    style
    String: either fit` (pad the edges to avoid cropping) or zoom (crop the edges to avoid padding).
Status Codes

List Redemption Locations

GET /design/(string: design_id)/redeemers

Get a list of business profiles that accept this cash design as payment for goods or services. If more than 100 locations accept the cash design, this API call currently returns only 100 of them.

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
  • 200 OK – Successful. The response body is a list of Profile JSON objects.
  • 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.

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).

The first time notes are issued based on a new cash design, WingCash publishes the cash design. Once published, a cash design can not be deleted.

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.
  • message_rules (array) – Optional array of MessageRule objects. Use this field to choose the templates for email and SMS messages.
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.
  • message_rules (array) – Optional array of MessageRule objects. Use this field to choose the templates for email and SMS messages.
Status Codes

Set the Icon

PUT /design/(string: design_id)/icon

Set or replace the icon for the cash design. (The cash design icon is distinct from the image. The image specifies the appearance of individual notes, while the icon represents the cash design network.) Provide a PNG, JPEG, or GIF file as the body of the request. The icon will be fit (with or without padding) in a 512x512 square.

If you use curl to call this API, use the -T option with a filename to provide the request body.

Permission Required

edit_design. See Permissions.

Request Headers
  • Authorization – See Authorization Header.
  • Content-Typeimage/png, image/jpeg, image/gif, or application/octet-stream if your app does not know the image format.
  • X-Image-Style – Optional image rendering style, either fit or zoom. zoom is the default.
Status Codes

Get the Icon URL

GET /design/(string: design_id)/icon

Get the URL of the rendered icon for the cash design.

Permission Required

view_design. See Permissions.

Request Headers
Status Codes
  • 200 OK

    Successful. The response body is a JSON object containing:

    url
    The URL of the final icon, or null if the icon is not set.
  • 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.

Get the Icon Preview URLs

GET /design/(string: design_id)/icon-previews

Get the icon preview URLs. Apps can use this API call to let users see the icon rendered with different options.

Permission Required

view_design. See Permissions.

Request Headers
Status Codes
  • 200 OK

    Successful. The response body is either an empty JSON object if the icon is not set, or an object containing:

    thumbnail
    An object containing:
    zoom
    The URL for a rendering of the icon thumbnail in zoom style.
    fit
    The URL for a rendering of the icon thumbnail in fit style.
    full
    An object containing:
    zoom
    The URL for a rendering of the full size icon in zoom style.
    fit
    The URL for a rendering of the full size icon in fit style.
  • 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.

Create a Distribution Plan

POST /design/(string: design_id)/plan/create

Create a distribution plan and add it to the cash design. Distribution plans are applicable only to brand cash. A distribution plan specifies how redeemers will be compensated for accepting brand cash.

The new plan will initially have the default distribution terms: the redeemer will receive a settlement in open loop cash that exactly matches the amount received in brand cash.

Permission Required

edit_design. See Permissions.

Request Headers
Request JSON Object
  • title – Required. The name of the new distribution plan. Up to 50 characters.
Status Codes
  • 200 OK – Successful. The response body is a JSON object containing plan_id.
  • 400 Bad Request – A parameter was invalid or incorrect. See InvalidRequest.
  • 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 or distribution plan could not be found.

Edit a Distribution Plan

PATCH /design/(string: design_id)/plan/(string: plan_id)

Edit an existing distribution plan. All fields are optional. To leave an attribute unchanged, exclude the attribute from the request.

Permission Required

edit_design. See Permissions.

Request Headers
Request JSON Object
  • title – Optional. The name of the distribution plan. Up to 50 characters.
  • recipients

    Optional. An updated table of recipients. Provide a list of JSON objects where each object contains:

    percentage
    String containing a decimal value up to 100. The percentage specifies the amount to distribute as a percentage of the amount of brand cash sent.
    loop_id
    String. If this percentage is to be distributed before redemption, loop_id should be the string 0. If the percentage is to be distributed after redemption, loop_id should be the design_id of the cash design.
    recipient_type
    String. May be discount (don’t distribute the percentage), static (distribute to a specific wallet), or redeemer (distribute to the merchant who redeemed the brand cash.) Other future possible values include processor and surcharge.
    recipient_id
    String. The profile ID of the recipient if recipient_type is static, otherwise 0.
Status Codes

Delete a Distribution Plan

DELETE /design/(string: design_id)/plan/(string: plan_id)

Delete a distribution plan.

Permission Required

edit_design. See Permissions.

Request Headers
Status Codes
  • 200 OK – Successful. The response body is an updated CashDesign JSON object.
  • 400 Bad Request – A parameter was invalid or incorrect. See InvalidRequest.
  • 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 – Either the distribution plan has already been deleted or the specified cash design or distribution plan 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

Delete a Cash Design

DELETE /design/(string: design_id)

Delete an unpublished cash design.

Note

Once a cash design is published, it can no longer be deleted; this API call will return an error. If you no longer want a published cash design to appear in the list of cash designs assigned to a profile, you can reassign the design permissions to another profile.

Permission Required

manage_design. See Permissions.

Request Headers
Status Codes
  • 200 OK – Successful. The response body is an empty JSON object.
  • 400 Bad Request – A parameter was invalid or incorrect. See InvalidRequest.
  • 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 – Either the cash design has already been deleted or the design could not be found.