How user-to-user cross-border payments work on Stellar
Overview
Laura in the USA wants to send money to Victor in Brazil.
Both Laura and Victor already have digital wallets they use to store, transfer, and trade Stellar-network tokens.
Laura wants to send her local currency, USD, but Victor wants to receive his local currency, BRL.
The following diagram shows how that payment – which involves 2 users, 2 wallets, and 2 anchors – unfolds on Stellar
It assumes both wallets and both anchors support interactive deposits and withdrawals as described in SEP-24 and user authentication as described in SEP-10. The anchor-to-wallet interactions are all handled in the background. The user experience should be pretty seamless.
Laura's wallet crawls USAnchor's stellar.toml to find and display info about their asset.
Laura opens her wallet and selects the option to deposit USD.
The wallet pings USAnchor's /info endpoint to find and display up-to-date fee info.
Laura's wallet crawls USAnchor's stellar.toml to find and display info about their asset.
The wallet makes a request to USAnchor's /transactions/deposit/interactive endpoint to initiate the deposit.
USAnchor's /transactions/deposit/interactive responds with the URL for a webapp Laura will use to complete her deposit.
The wallet serves USAnchor's webapp in an iframe
Laura's KYC verification
Using the anchor webapp, Laura enters any info USAnchor requires before accepting a deposit, including KYC. If Laura made a previous deposit, USAnchor should already have KYC info on hand.
The wallet pings USAnchor's /info endpoint to find and display up-to-date fee info.
Laura deposits USD and receives USD tokens
When Laura passes USAnchor’s KYC check, the webapp walks her through the rest of the deposit.
In this case, it directly connects to Laura's bank to initiate the deposit, though some anchors simply display information users need to complete a deposit manually, like a bank account number.
Laura's funds transfer to USAnchor's account via ACH.
That transfer happens on a traditional banking system, so it can take a few days.
USAnchor detects Laura’s deposit as it arrives and transfers USD tokens to her wallet’s Stellar account.
That transfer happens on the Stellar network, so it just takes a few seconds.
02 Laura sends money to Victor
Laura makes the payment
Using her funded wallet, Laura specifies the amount of USD she’d like to send, and the currency Victor would like to receive, BRL.
USD-to-BRL conversion
USAnchor detects Laura’s deposit as it arrives and transfers USD tokens to her wallet’s Stellar account.
Payment is complete
Using her funded wallet, Laura specifies the amount of USD she’d like to send, and the currency Victor would like to receive, BRL.
03 Victor withdraws from his wallet
Victor starts his withdrawal
Victor's wallet crawls AnchorBrazil's stellar.toml to find and display info about their asset.
Victor opens his wallet app, pleased to find the payment from Laura, and enters the amount of BRL he’d like to withdraw.
The wallet pings AnchorBrazil's /info endpoint to find and display up-to-date fee info.
The wallet pings AnchorBrazil’s WEB_AUTH_ENDPOINT, goes through challenge/response, receives a JWT token to authenticate the user session.
The wallet pings AnchorBrazil’s /transactions/withdraw/interactive endpoint to initiate the withdrawal
AnchorBrazil's /transactions/withdraw/interactive responds with the URL for a webapp Victor will use to complete his withdrawal, along with an id the wallet uses to keep track of Victor's transaction.
The wallet opens the webapp in an iframe.
Victor's KYC Verification
Using the anchor webapp, Victor enters his bank account and KYC info.
AnchorBrazil analyzes Victor’s KYC info — how they do that is up to them.
Victor's withdrawal is completed
To find out if Victor completed his interaction with AnchorBrazil, the wallet polls AnchorBrazil's /transaction endpoint with the id provided in the /transactions/withdraw/interactive above.
When the /transaction endpoint returns pending_user_transfer_start, the wallet displays a confirmation screen summarizing the withdrawal to Victor.
The wallet sends the specified amount of BRL tokens to AnchorBrazil’s Stellar address.
This transaction happens on the Stellar network, and only takes a few seconds.
AnchorBrazil transfers an equivalent amount of BRL from their bank account to Victor’s bank account via TED.
That transfer happens on a traditional banking system, but TED transfers are faster than ACH, and usually complete within a single business day.