Wallet API Calls

Show the Wallet

GET /wallet/info

Get all wallet information for the authenticated profile.

Permission Required:
 

view_wallet. 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 JSON object with these attributes:

    profile
    A ProfileDetail object describing the authenticated profile.
    related
    A list of Profile or ProfileDetail objects providing info about profiles linked with the authenticated profile. Includes profiles managed by the authenticated personal profile and featured profiles. Profiles managed by the authenticated personal profile are represented as ProfileDetail objects.
  • 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.

Find Profiles

GET /me

Get the public information about the authenticated profile.

Permission Required:
 

None.

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

Get the public information about the specified profile.

Permission Required:
 

None.

Query Parameters:
 
  • version – Optional. If provided, must be 1.
Status Codes:

Find people or businesses either at WingCash or at a service linked from the authenticated profile.

Permission Required:
 

list_friends. See Permissions.

Request Headers:
 
Query Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
  • q – Search text. Must contain no more than 1000 characters. When searching WingCash UIDs, the query text must contain at least 3 non-whitespace characters.
  • uid – Optional string. Specifies which service to search and which credentials to apply. The UID must be listed in the confirmed_uids of the authenticated profile. Defaults to the wingcash_uid attribute of the authenticated profile. Email UIDs are not accepted.
  • limit – Optional integer. Specifies the maximum number of results to retrieve. The default is 20.
  • offset – Optional integer. Specifies how many search results to skip.
  • serial_numbers – Optional string. A space-delimited list of cash page serial numbers to be sent soon. This filters the list of available recipients. Use this when the user has already chosen a specific page or list of pages to send.
  • filters
    Optional string. A space-delimited list of filters to apply. The available filters are:
    business
    List only business profiles.
    individual
    List only personal profiles.
    exclude_self
    Exclude the authenticated profile, even if it matches.
  • latitude – Optional geospatial latitude. If both latitude and longitude are provided, the search results will be sorted with the closest businesses listed first. Example: 40.5678
  • longitude – Optional geospatial longitude. See also latitude. Example: -111.9876
Status Codes:
  • 200 OK

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

    results
    A list of SearchProfilesResult objects.
    more
    Boolean. True if there are more results.
  • 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.
  • 503 Service Unavailable – WingCash was unable to access the external service. The response body contains an InvalidRequest object with an error value of either external_communication_error (the service may be unavailable) or external_access_expired (the profile’s access token for the service has expired).

Send Cash

GET /wallet/presend

Get information about what the authenticated profile can send to a particular recipient. Apps may use this call when the user has chosen a recipient and the user wants to choose what kinds of cash to send and how much. This call is optional; some apps may use POST /wallet/send directly.

Permission Required:
 

send_cash. See Permissions.

Request Headers:
 
Query Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
  • recipient_uid – 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.
  • sender_uid – 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.
  • 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:

    must_accept_policy
    Boolean. If true, the app must ask the user to accept the following policy statement before continuing:

    Like physical cash transfers, transfers through this service are final and non-refundable. Only the recipient can offer refunds, so you should send cash only to people and businesses you trust. This policy is explained in the Terms of Service.

    loops
    List of SendableAmount objects. Specifies 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.
    any_accepted
    Boolean. When true, the recipient accepts all types of cash. When false, some of the loops may have the missing_agreement flag set, in which case the app’s UI must clearly distinguish cash types that are not accepted by the recipient. Note that users may be able to send types of cash not accepted by the recipient if the non_payment boolean is set when calling POST /wallet/send. Furthermore, WingCash does not allow users to send, in a single transfer, both cash accepted by the recipient and cash not accepted by the recipient.
    force_private
    Boolean. True if WingCash will force the transfer to be private; the app’s UI should reflect this by disabling, removing, or constraining the privacy control.
    support_paycode
    Boolean. True if the recipient accepts payment codes. If the recipient is a business and does not accept payment codes, the app should warn the user that the cash will be sent immediately, without a payment code; only the recipient can offer refunds.
    message_split
    Boolean. True if the chosen service splits messages into a subject and body, in which case the UI should provide two message fields (subject and body) rather than one. (LinkedIn is the only current example.)
    recipient_info
    A UIDInfo object about the recipient. (If the is_individual attribute of recipient_info is false, the recipient is a business.)
    sender_can_send_direct
    Boolean. True if the sender can send direct messages to the recipient through the service specified by recipient_uid. This is null if the relationship is not known.
    recipient_can_send_direct
    Boolean. True if the recipient can send direct messages to the sender through the service specified by recipient_uid. This is null if the relationship is not known.
  • 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.
POST /wallet/send

Send cash.

Permission Required:
 

send_cash. See Permissions.

Request Headers:
 
Form Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
  • recipient_uid – 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.
  • amounts

    Required. 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 0 and $0.25 of loop 1023, amounts should be:

    0-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 (such as open-loop cash.) For example, to send USD $1.00 of any cash accepted by the recipient, use the following amounts:

    any-USD-1.00

    Apps should use the any feature especially when sending to recipients who accept a payment code. The any feature lets WingCash defer the decision of what types of cash to send until the recipient accepts the payment code.

    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
  • sender_uid – 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.
  • 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.
  • accepted_policy – Optional. Set to true only if the policy statement described in GET /wallet/presend was presented to the user as part of this transfer and the user accepted the policy statement. Leave this parameter out or set it to false if the user did not accept the policy or if the policy statement was not presented to the user as part of this transfer.
  • non_payment – Optional. If the user wants to send cash to a recipient who does not accept the type of cash being sent, your app should require the user to acknowledge that the transfer is not for payment of products and services. Present the user with an option to enable non-payment using a checkbox labeled Send Anyway or similar. Set this parameter to true only if the user decided to send a non-payment transfer.
  • message – Optional. The message to send. WingCash accepts up to 10000 characters (although the message will be trimmed to 140 characters when sending a status update to Twitter.) Ignored when sending to a service that splits messages into a subject and body.
  • message_subject – Optional. The message subject line. WingCash accepts up to 100 characters. Normally ignored except when sending to a service that splits messages into a subject and body.
  • message_body – Optional. The message body. WingCash accepts up to 10000 characters. Normally ignored except when sending to a service that splits messages into a subject and body.
  • notify_via – Optional. Specifies how to send the message through the external service. When sending through Twitter to a follower, this can be tweet, direct, or tweet direct (to send both a status update and a direct message.)
  • require_recipient_email – Optional boolean. 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.* – 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 – 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:

Send To a Previously Added Financial Institution Account

Use these calls to send cash to a bank or credit union account already registered with the profile. Users must select how to send the cash and pay the deposit fee (if any), but the selection process can be made simple. See the WingCash web site for a reasonable way to present the deposit offers and options.

GET /wallet/account/(string: account_id)/presend

Get the offers and options available for sending open loop cash to an account at a bank or credit union registered with the profile. Apps should use this call after the user has chosen a destination account and amount to send.

Permission Required:
 

send_to_account. See Permissions.

Request Headers:
 
Query Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
  • amount – Required. Amount to send. This must be no more than the total of open loop cash the profile holds.
  • serial_numbers – Optional. A space-delimited list of cash page serial numbers 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:

    offers
    List of DepositOffer objects. One or more financial institutions will transfer funds to a bank or credit union with these terms. The app should allow the user to choose one of the listed offers.
  • 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.
POST /wallet/account/(string: account_id)/send

Send open loop cash to a bank or credit union account registered with the profile. Before using this API call, apps must use the GET /wallet/account/(string:account_id)/presend API call to discover the available offers and fee payment options.

Permission Required:
 

send_to_account. See Permissions.

Request Headers:
 
Form Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
  • amount – Required. Amount to send. This must be no more than the total of open loop cash the profile holds.
  • offer_name – Required. The name of the DepositOffer the user chose.
  • fee_option_name – Required. The name of the DepositOption the user chose. Either add or subtract.
  • serial_numbers – Optional. A space-delimited list of cash page serial numbers to send. Use this when the user has already chosen a specific page or list of pages to send.
  • 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.
  • dedup_id – 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:

Receive Cash

POST /wallet/receive

Receive cash using a payment code. Point of sale terminals use this API call.

Permission Required:
 

receive_cash. See Permissions. Unlike most other calls, soft-expired access tokens are accepted for this call.

Request Headers:
 
Form Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
  • paycode – Required. The payment code provided by the sender.
  • currency – Required currency code. Must be 3 uppercase letters. See ISO 4217.
  • amount – Required. The amount to receive.
  • total_due – Optional. The total amount due, including money to be received outside WingCash (such as physical cash). Providing this information improves WingCash reports. When provided, the total_due must be greater than or equal to amount.
  • total_tax – Optional. The sales tax portion of the total due. When both total_due and total_tax are provided, the total_tax must be less than or equal to total_due.
Status Codes:
  • 200 OK

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

    transfer
    Info about the transfer as a Transfer object.
    sender
    The Profile who sent the cash.
    amount_received
    The amount received. The amount received normally matches the amount requested. The amount received may change if the recipient resubmits the payment code during the correction period after a payment.
  • 400 Bad Request

    The parameters are not valid. The response body contains an InvalidRequest object. Common error codes for this call include:

    code_not_found
    The payment code is in a valid format but does not exist.
    code_already_used
    The payment code has been used already and can not provide any more cash.
    code_limited
    The requested amount was greater than the amount available for the payment code.
  • 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.