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) ortimestamp
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) orasc
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.
- version – Optional. If provided, must be
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, thesync_ts
value is also updated. Thesync_ts
value can be much later than the transfer start or end timestamps. This API call downloads transfers since a particularsync_ts
timestamp. Thesync_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 thelast_sync_ts
value from the previous batch. Note: if you also providetransfer_id
, transfers with the samesync_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 identicalsync_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 isnull
. 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 isnull
. Use this value as thesync_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. Ifcount_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.
- version (string) – Optional. If provided, must be
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: - 200 OK – Successful. The response body is a TransferDetail JSON object.
- 400 Bad Request – The parameters are not valid. The response body contains an InvalidRequest object.
- 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 this function.
- version – Optional. If provided, must be
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: - Authorization – See Authorization Header.
- Content-Type –
application/x-www-form-urlencoded
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
isnot_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
andsend_design
transfers), you need themanage_sent
permission. If the transfer was initiated by the recipient (such asbill
transfers), you need themanage_received
permission. See Permissions.Request Headers: - Authorization – See Authorization Header.
- Content-Type –
application/x-www-form-urlencoded
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: - 200 OK –
Successful. The response body is a JSON object with these attributes:
transfer
- The updated TransferDetail object.
- 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.
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: - Authorization – See Authorization Header.
- Content-Type –
application/x-www-form-urlencoded
Form 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:
transfer
- The updated TransferDetail object.
- 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 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. SeePOST /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 thecurrency
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 choosemyapp
as a prefix and you want to store atransaction_id
field, you should name your fieldappdata.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. Oncededup_id
is set appropriately, you can safely re-transmit the transfer request as needed.
Status Codes: - 200 OK –
Successful. The response body is a JSON object with these attributes:
transfer
- A TransferDetail object.
profile
- The sender’s ProfileDetail object, updated to reflect the new amounts in the wallet.
- 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.
- version (string) – Optional. If provided, must be
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. SeePOST /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 thecurrency
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 is1800
, 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 choosemyapp
as a prefix and you want to store atransaction_id
field, you should name your fieldappdata.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. Oncededup_id
is set appropriately, you can safely re-transmit the transfer request as needed.
Status Codes: - 200 OK –
Successful. The response body is a JSON object with these attributes:
transfer
- A TransferDetail object.
profile
- The sender’s ProfileDetail object, updated to reflect the new amounts in the wallet.
- 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.
- version (string) – Optional. If provided, must be