Guides

Wallet Order Reservations

Suggest Edits

Every card purchase starts with a Wallet Order Reservation. This page will describe important concepts and use cases related to card processing with Wyre.

For partners using Wyre Checkout, simply call our reservations endpoint and redirect the user to the provided URL.

For white label card processing implementations, you will need to call the reservations endpoint and grab the reservation ID, to subsequently be supplied with the direct card processing endpoint. You can also use the reservations endpoint to lock exchange rates.

📘

Note

  • The generated reservation ID may only be used once and is good for 15 minutes.
{
    "url": "https://pay.sendwyre.com/purchase?accountId=AC_99B4YHQYR2Y&reservation=3ZFYNFGUHBER9MZW7MND&redirectUrl=sendwyre.com&utm_campaign=AC_99B4YHQYR2Y&utm_medium=widget&utm_source=checkout",
    "reservation": "3ZFYNFGUHBER9MZW7MND"
}

Rates Locking

To use rates locking you must use specific fields.

When sourceAmount/destAmount is specified, amountIncludeFees is mandatory.
When amount is specified, you are not locking the rates.

Necessary Fields for Rates Locking:
sourceAmount OR destAmount, not both,
amountIncludeFees Ex. true,
paymentMethod Ex. "debit-card",
sourceCurrency Ex. "USD",
destCurrency Ex. "ETH",
dest Ex. "ethereum:0x9E01E0E60dF079136a7a1d4ed97d709D5Fe3e341",
referrerAccountId Ex. "AC_XXXXXXXXXX",
country Ex. "US"

How amountIncludeFees Works:

amountIncludeFees = false
Fees are added on top: $100 + fees will be charged to the user. The user receives the full $100 in value.

amountIncludeFees = true
Fees will be subtracted from the amount: $100 - fees will be sent to the user's wallet. The user receives the amount less the fees.

📘

Rate Locking Expiration

Locked quotes are good for 15 minutes. After that, the reservation is expired.

curl -X POST \
  API_URL/v3/orders/reserve \
  -H 'Authorization: Bearer WYRE_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
    "sourceAmount": "10",
    "amountIncludeFees": false,
    "paymentMethod": "debit-card",
    "sourceCurrency": "USD",
    "destCurrency": "ETH",
    "dest": "ethereum:0x9E01E0E60dF079136a7a1d4ed97d709D5Fe3e341",
    "redirectUrl": "https://www.sendwyre.com",
    "failureRedirectUrl": "https://www.sendwyre.com",
    "referrerAccountId": "AC_XXXXXXXXXX",
    "country":"US",
    "lockFields": ["sourceAmount"]
    }'

Next: You need to GET the Rate Locked Reservation endpoint. This will return the response below, and allows you to display rates and fees in your UI before completing the transaction.

{
   "amount":null,
   "sourceCurrency":"USD",
   "destCurrency":"ETH",
   "dest":"ethereum:0x9E01E0E60dF079136a7a1d4ed97d709D5Fe3e341",
   "referrerAccountId":"AC______AAAA",
   "sourceAmount":null,
   "destAmount":0.02,
   "amountIncludeFees":true,
   "street1":"1550 Bryant Street",
   "city":"San Francisco",
   "state":"CA",
   "postalCode":"94103",
   "country":"US",
   "firstName":"",
   "lastName":"",
   "phone":"...",
   "email":"",
   "lockFields":[
      "sourceAmount",
      "destAmount",
      "amountIncludeFees",
      "paymentMethod",
      "country",
      "sourceCurrency",
      "destCurrency",
      "dest",
      "referrerAccountId"
   ],
   "redirectUrl":"http://google.com",
   "failureRedirectUrl":"http://google.com",
   "paymentMethod":"debit-card",
   "referenceId":null,
   "hideTrackBtn":null,
   "quote":{
      "sourceCurrency":"USD",
      "sourceAmount":8.89,
      "sourceAmountWithoutFees":5.45,
      "destCurrency":"ETH",
      "destAmount":0.013,
      "exchangeRate":0.002388613861386138642579298795,
      "equivalencies":{
         "GUSD":5.26,
         "USDC":5.255737,
         "EUR":4.44,
         "USDT":5.255217,
         "GBP":4.03,
         "DAI":6.081825531005859375,
         "USD":5.25,
         "CAD":6.93,
         "BUSD":5.255736808466774984,
         "USDS":5.255737,
         "HUSD":5.25573681,
         "BTC":0.00039169,
         "ETH":0.013000000000000000,
         "AUD":7.38,
         "PAX":5.255736808466774984,
         "WETH":0.013000000000000000
      },
      "fees":{
         "ETH":0.007000000000000000,
         "USD":0.51
      }
   },
   "quoteLockRequest":true
}

For Card Processing API or Apple Pay White label you must use the values in the quote object as the rates are locked. For this reservation, the quote cannot be changed.

Internationalization

The API supports international address details. A province or administrative area, such as a county, can be entered in the "state" parameter. The example below features an address in Norway, which has counties instead of states. The county name is listed in the state field.

Note: Localized presentment currencies will enjoy higher conversion rates, set local source currencies whenever possible.

{
    "sourceAmount": "100",
    "amountIncludeFees": false,
    "paymentMethod": "debit-card",
    "sourceCurrency": "NOK",
    "destCurrency": "BTC",
    "dest": "bitcoin:1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2",
    "referrerAccountId": "AC_XXXXXXXXXX",
    "street1": "Bergjelandsgt. 30",
    "postalCode":"4012",
    "city": "Stavanger",
    "state":"Rogaland",
    "country":"NO"
}

Updated about 2 years ago