Transfer API Calls

Use these API calls to view and modify transfers you participate in.

List Transfers

GET /wallet/history

List transfers in which the authenticated profile is a participant (the sender, recipient, provider, etc.)

Permission Required:
 

view_history. See Permissions.
Request Headers:
 
Query Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
  • offset – Optional integer. Specifies the number of transfers to skip. The default is 0.
  • limit – Optional integer. Specifies the maximum number of transfers to retrieve. The default is 100.
  • order_column – Optional string. Specify start to order by the transfer creation time (the default) or timestamp to order by the date and time when the transfer last changed.
  • order_direction – Optional string. Specify desc to return the latest transfers first (the default) or asc to return the oldest transfers first.
  • appdata.* – Optional app-specific transfer data to match, one value per field. Replace the * with field names appropriate for your app. You may filter by a total of up to 128 characters (the total number of characters in keys and values).
Status Codes:
  • 200 OK –

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

    results
    A list of Transfer objects. May be an empty list.
    more
    Boolean. True if there are more transfers.
  • 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.

Sync Transfers

POST /wallet/history_sync

Download a batch of new and updated transfers for the authenticated profile. This is similar to GET /wallet/history, but this version is designed for creating a synchronized external copy of the transfer records. This call makes it possible to ensure no transfers or updates are skipped, even when transfers are numerous and frequent.

Unlike the GET /wallet/history API call, the order and segmentation of the results is probably not optimal for display to users, however, you could use this API call to download the transfer records into your database and later display the transfers to users using queries against your database.

Every transfer has a hidden sync_ts (sync timestamp) value. Whenever a transfer is updated, the sync_ts value is also updated. The sync_ts value can be much later than the transfer start or end timestamps. This API call downloads transfers since a particular sync_ts timestamp. The sync_ts value is not intended for display to users and may be updated at any time.

Note

Different profiles can have a different sync_ts for the same transfer.

Note

Due to clock skew and related issues, sometimes transfer updates are not available until a few seconds or minutes later. To compensate for this, your code should backdate the sync_ts value by a short time interval (5 minutes is suggested) when starting a sync operation to reveal any updates missed earlier.

Permission Required:
 

view_history. See Permissions.
Request Headers:
 
Request JSON Object:
 
  • version (string) – Optional. If provided, must be 1.
  • access_token (string) – Optional alternative to the Authorization Header.
  • sync_ts (string) – Required. Only transfers with a sync_ts after the given ISO 8601 timestamp will be included in the results. For the first batch, the string 1970-01-01T00:00:00Z is recommended. For later batches, set this parameter equal to the last_sync_ts value from the previous batch. Note: if you also provide transfer_id, transfers with the same sync_ts value as specified by this parameter may be included in the results.
  • transfer_id (string) – Optional. Provide the id of the last transfer downloaded in the previous batch. Leave empty or missing if this is the first batch. This parameter helps ensure all updates are downloaded even if multiple transfers have identical sync_ts values.
  • limit (integer) – Optional. Specifies the maximum number of transfers to retrieve in this batch. The default is 1000.
  • count_remain (bool) – Optional. If true, count the remaining number of transfers to be downloaded and include the remain attribute in the response. This is useful for showing the user a progress bar. Because enabling this parameter may reduce the speed of the download, you should generally enable this parameter only for the first batch of a sync operation.
Status Codes:
  • 200 OK –

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

    results
    A list of Transfer objects. May be an empty list.
    more
    Boolean. True if there are more transfers to download.
    first_sync_ts
    The sync_ts of the first transfer in the results, in ISO 8601 format and in UTC. If there are no results, this value is null.
    last_sync_ts
    The sync_ts of the last transfer in the results, in ISO 8601 format and in UTC. If there are no results, this value is null. Use this value as the sync_ts parameter to download the next batch.
    remain
    If the count_remain request parameter is true, this response attribute contains the number of transfers to be downloaded after this batch. If count_remain is missing or false, this response attribute is not provided.
  • 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.

Get Transfer Information

GET /t/(string: transfer_id)

Get the state of a transfer.

Permission Required:
 

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

Change a Payment Code

POST /t/(string: transfer_id)/change_paycode_expiration

Change the expiration of a payment code attached to a transfer sent by the authenticated profile.

Permission Required:
 

manage_sent. See Permissions.
Request Headers:
 
Form Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
  • paycode – Required. The payment code to change.
  • expire_seconds – Required. The number of seconds until the payment code should expire. Maximum 10 years.
Status Codes:
  • 200 OK –

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

    transfer
    The updated TransferDetail object.
  • 400 Bad Request – Either the transfer is not waiting for a payment code (in which case error is not_waiting) or 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.

Retract a Transfer

POST /t/(string: transfer_id)/retract

Retract a transfer you initiated.

Permission Required:
 

Depends on the transfer. If the transfer was initiated by the sender (such as profile_to_profile and send_design transfers), you need the manage_sent permission. If the transfer was initiated by the recipient (such as bill transfers), you need the manage_received permission. See Permissions.
Request Headers:
 
Form Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
  • reason –

    Required. A code that indicates the reason for the retraction. The available reasons are:

    wrong_amount
    The wrong amount was sent or requested.
    wrong_recipient
    The wrong sender or recipient was specified.
    invalid_address
    The invitation was sent to an invalid address.
    never_got_invitation
    The sender or recipient never got the invitation.
    refused
    The recipient refused the cash. (Accepted only when the sender initiated the transfer.)
    canceled
    The sender canceled the transfer. (Accepted only when the recipient initiated the transfer.)
    too_long
    The recipient or sender took too long to decide.
    recipient_unable
    The recipient is unable to accept the cash. (Accepted only when the sender initiated the transfer.)
    sender_unable
    The sender is unable to send the cash. (Accepted only when the recipient initiated the transfer.)
    wrong_payment_form
    The sender or recipient requires a different form of payment.
    unable_to_sign_up
    The sender or recipient can not sign up for WingCash.
    not_available
    WingCash is not yet available in the sender or recipient’s area.
    computer_error
    A computer or network error is stopping the transfer.
    other
    Other reason.
Status Codes:

Skip a Transfer Delay

POST /t/(string: transfer_id)/skip

Skip a delay in a transfer you initiated. Use this to bypass either a payment code or an optional delay period.

Permission Required:
 

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

Send To Any Financial Institution Account

POST /wallet/send-dfi

Send cash to a bank or credit union account. Unlike POST /wallet/account/(string:account_id)/send, you can send to any account. The receiving account must accept cash in the currency you are sending. See POST /wallet/send-fx for exchanging currency.

Permission Required:
 

send_to_account. See Permissions.
Request Headers:
 
Request JSON Object:
 
  • version (string) – Optional. If provided, must be 1.
  • access_token (string) – Optional alternative to the Authorization Header.
  • currency (string) – Required string containing a currency code. Must be 3 uppercase letters. See ISO 4217.
  • amount (string) – Required string. Amount to send. The currency is given by the currency field. This must be no more than the total of open loop cash the profile holds in the specified currency.
  • fee (string) – Required string. The amount of the fee for the transfer, which can be 0. The currency is given by the currency field.
  • recipient_about (object) – A RecipientAbout object. Required.
  • recipient_account (object) – A RecipientAccount object. Required.
  • 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:

Exchange Currency and Send To Any Financial Institution Account

POST /wallet/send-fx

Exchange currency and send cash to a bank or credit union account. Unlike POST /wallet/account/(string:account_id)/send, you can send to any account. See POST /wallet/send-dfi if you don’t need to exchange currency.

Permission Required:
 

send_to_account. See Permissions.
Request Headers:
 
Request JSON Object:
 
  • version (string) – Optional. If provided, must be 1.
  • access_token (string) – Optional alternative to the Authorization Header.
  • currency (string) – Required string containing the pre-exchange currency code. Must be 3 uppercase letters. See ISO 4217.
  • amount (string) – Required string. Amount to send before the currency exchange. The currency is given by the currency field. This must be no more than the total of open loop cash the profile holds in the specified currency.
  • fee (string) – Required string. The pre-exchange amount of the fee for the transfer, which can be 0. The currency is given by the currency field.
  • recipient_about (object) – A RecipientAbout object. Required.
  • recipient_account (object) – A RecipientAccount object. Required. The account must accept cash in the post-exchange currency.
  • fx (object) – An FXParams object. Required. The FXParams object specifies the post-exchange currency, the amount, and how to perform the exchange.
  • hold_seconds (integer) – The number of seconds to pause before completing the transfer. Defaults to 0. A common value is 1800, meaning 30 minutes, which is the time advised by US regulations to allow the sender to cancel or alter a remittance transfer.
  • 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: