How user-to-user cross-border payments work on Stellar

Overview

Globe Illustration
  • 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.

What the user sees

1

Laura funds her account

Deposit screen
  • Laura chooses to deposit USD
  • Enters her KYC info
  • Receives deposit instructions
  • Transfers funds via ACH
  • Receives USD tokens in her wallet
See what happens in the background
2

Laura sends money to Victor

Deposit screen
  • Laura enters Victor’s wallet address
  • Chooses to send USD
  • And for Victor to receive BRL
  • Confirms the payment
  • Victor receives the payment in his wallet a few seconds later
See what happens in the background
3

Victor withdraws from his wallet

Deposit screen
  • Victor selects the amount of BRL he’d like to withdraw
  • Enters his KYC info
  • Enters his bank account info
  • Confirms the withdrawal
  • Receives BRL in his bank account via TED
See what happens in the background

What happens in the background

1

Laura funds her account

Laura starts her deposit

  • 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.
  • Phone icon
    Arrow right
    Anchor icon
    The wallet pings USAnchor's /info endpoint to find and display up-to-date fee info.
  • Phone icon
    Arrow right
    Anchor icon
    The wallet pings USAnchor’s WEB_AUTH_ENDPOINT, goes through challenge/response, receives a JWT token to authenticate the user session.
  • Phone icon
    Arrow right
    Anchor icon
    The wallet makes a request to USAnchor's /transactions/deposit/interactive endpoint to initiate the deposit.
  • Phone icon
    Arrow left
    Anchor icon
    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.
  • USAnchor analyzes Laura’s KYC info — how they do that is up to them.

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.
  • Anchor icon
    Arrow left
    Phone icon
    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.
2

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

  • Phone icon
    Arrow right
    Stellar icon
    The wallet executes a pathpayment on the Stellar network, which debits USD from Laura’s account, converts it to BRL using the built-in network orderbooks, and credits Victor with that BRL, all in a single transaction.

Payment is complete

  • Victor gets the BRL in his wallet app a few seconds later.
3

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.
  • Phone icon
    Arrow right
    Anchor icon
    The wallet pings AnchorBrazil's /info endpoint to find and display up-to-date fee info.
  • Phone icon
    Arrow right
    Anchor icon
    The wallet pings AnchorBrazil’s WEB_AUTH_ENDPOINT, goes through challenge/response, receives a JWT token to authenticate the user session.
  • Phone icon
    Arrow right
    Anchor icon
    The wallet pings AnchorBrazil’s /transactions/withdraw/interactive endpoint to initiate the withdrawal
  • Phone icon
    Arrow left
    Anchor icon
    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

  • Phone icon
    Arrow right
    Anchor icon
    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.
  • Phone icon
    Arrow left
    Anchor icon
    When the /transaction endpoint returns pending_user_transfer_start, the wallet displays a confirmation screen summarizing the withdrawal to Victor.
  • Phone icon
    Arrow right
    Stellar icon
    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.