Transfers and Exchanges

Constructing the Transfer Request

The Transfer API offers flexibility in the intents that it accepts. There are three primary constructs that together create this functionality:

Source and Destination

The source of the transfer is the system from which funds are being pulled, while the dest is, somewhat unsurprisingly, the final destination of the funds. These parameters are SRNs and can be different types - accounts, payment methods, wallets, or blockchain addresses.

Eligibility varies across these types as well as between specific instances for usage as source or destination. e.g. a bitcoin address may be used (currently) only as a destination, while some payment methods may be able to be used for either source or destination.

Movement vs Exchange

The API offers two parameters, sourceCurrency and destCurrency, which collectively control the exchange behavior of the transfer.

If only sourceCurrency is supplied, or both are supplied and are identical, the transfer will perform no exchange and the currency will remain in its original form.

If the two are different, then an exchange is performed to convert the sourceCurrency taken from the source to the destCurrency.

Totals

There are three common ways to express the numeric totals involved in your Transfer:

Amount of money to process

You indicate the amount to move or convert. Fees are added on top of your indicated subtotal, and the resulting final total is withdrawn/requested from the source.

In this case, specify only sourceAmount, and amountIncludesFees will default to false.

Total to withdraw

You want to indicate the total amount that will be withdrawn/requested from the source, inclusive of fees.

In this case, specify sourceAmount and also specify amountIncludesFees=true.

Total to arrive

You want to indicate the total amount that will hit the destination. The system will compensate in fees and exchange rate to accomplish it.

In this case, specify only destAmount, and amountIncludesFees will default to false.

Auto Confirmation Settings

When autoConfirm is false, the returned transfer details can be used to present associated fees to the user before confirmation. The rates are locked for 15m if fiat-fiat or no exchange, 10m for crypto exchanges (including stablecoins). Unconfirmed transfers will expire after this locked period. If the transfer expires you'll have to reissue the transfer request and confirm the new transfer.

You may also instead automatically confirm the transfer by supply autoConfirm=true to skip the followup price confirmation.

🚧

Using Masquerade

If you're requesting a transfer for a sub-account because you're acting on behalf of the sub-account holder, you will need to use the masqueradeAs query parameter.

Transfer Fields

Transfer Lifecycle

As funds are transferred from the source Wyre account to the destination, the Transfer will go through a series of different states, represented through their status. Below is an outline of the different statuses and what they mean:

PREVIEW - a preview Transfer. These Transfers cannot be confirmed and funds will never move on them. They're created by specifying the 'preview=true' parameter at time of Transfer creation.

UNCONFIRMED - a Transfer with a valid quote. This is the default state for newly created Transfers. These Transfers must be confirmed before they're executed. Transfers will wait UNCONFIRMED for some about of time, after which if they are sill UNCONFIRMED they will transition to EXPIRED.

PENDING - a Transfer in the pending state means we're working on moving the money to its destination. (It does not require any further action from your side).

COMPLETED - once a Transfer is fully executed and the funds have been confirmed at the destination its status will change to COMPLETED

EXPIRED - any UNCONFIRMED Transfer that is not confirmed inside their 30 second confirmation window will transition to EXPIRED

FAILED - if a Transfer cannot be completed for any reason its status will change to FAILED. If there's anything we can do to make sure the Transfer goes through we will reach out via support channels before failing a transfer.

REVERSED - if a Transfer is reversed at a later time for any reason its status will change to REVERSED. This happens with ACH Payouts, for example, where Wyre's banking partner may notify Wyre at a later time.

See the below diagram for the state diagram of the different Transfer statuses.

In a normal situation the lifecycle of a Transfer looks like this:

1. Creating a Transfer and getting an exchange rate quote
2. Confirming a quote
3. Transfer transitions from PENDING to COMPLETED after funds are deposited (See Getting Transfer status updates)

Transfer Callbacks

Transfer callbacks are triggered when the notifyUrl is being used within the create transfer endpoint.

When callbacks are sent

Transfer Callbacks are sent whenever an initial transaction is created.

Callback Acceptance and Retries

Your system should respond to the callback request with a 200 response. We only attempt to send the request once, but we may introduce automatic retries in the future. We can manually resend callbacks upon request.

Payload

The callback payload will be a JSON representation of the transfer id that has caused the callback to trigger. An example of such a notification can be found below:

{
  "subscriptionId": "DA_CJN7LL2P7ZY",
  "trigger": "transfer:TF_P6MCNQ3GWFD"
}

Resolve the Transfer Id

You can resolve the transfer id received from the callback to get more details about the transfer such as the current status. This is done using the Get Transfer endpoint like below.

GET https://api.testwyre.com/v3/transfers/TF_P6MCNQ3GWFD

Blockchain Specific Transfer Cases

Stellar

Doing a stellar transfer from an external address to a Wyre address requires the User ID in the Memo. Transferring from a Wyre address requires the memo attached to the end of the address.
Example: stellar:GD7WXI7AOAK2CIPZVBEFYLS2NQZI2J4WN4HFYQQ4A2OMFVWGWAL3IW7K:LEMNM383ACX

📘

To view transfer history of a specific wallet or account

https://api.sendwyre.com/v2/transfers/wallet:WA_XXXXXXXXXXX
https://api.sendwyre.com/v2/transfers/account:WA_XXXXXXXXXX