Guides

Card Onramps for your Defi App

Suggest Edits
1200

We provide the simplest and most secure card onramp solution available. Get up and running in weeks and accept cards from anywhere in the world.

📘

High Level Flow:

  1. Create a Wallet Order Reservation to define your order request.
  2. For white label solutions Create an Order to send payment details.
  3. Check for Auth Codes
  4. Use Authorize Orders to authenticate the payment.
  5. Verify the order status

1. Creating Wallet Order Reservations

The first step in every card payment is to create a Wallet Order Reservation. This allows you to lock in the details for the order in an immutable way from your server before taking in payment details.

The generated reservation wallet order ID may only be used once. If the order fails, the ID will become unusable. Any callbacks issued on behalf of the order will use the same order ID, so it can be useful for correlating Wyre order to data in your own database. Reservations are good for one hour. Learn more about Wallet Order Reservations.

{
    "amount": "25",
    "paymentMethod": "debit-card",
    "sourceCurrency": "USD",
    "destCurrency": "BTC",
    "dest": "wallet:WA_N784BHR6XTX",
    "autoRedirect": true,
    "redirectUrl": "https://www.sendwyre.com",
    "lockFields": [
        "destCurrency",
        "dest"
    ],
    "referrerAccountId": "AC_JVPFPWYQH4B",
    "country": "US"
}

{
    "url": "https://pay.testwyre.com/purchase?accountId=AC_JVPFPWYQH4B&country=US&amount=25&redirectUrl=https%3A%2F%2Fwww.sendwyre.com&utm_campaign=AC_JVPFPWYQH4B&destCurrency=BTC&utm_medium=widget&paymentMethod=debit-card&reservation=7GY6L2HCJ4V4LR4QG29P&sourceCurrency=USD&dest=wallet%3AWA_N784BHR6XTX&utm_source=checkout",
    "reservation": "7GY6L2HCJ4V4LR4QG29P"
}

If you implement our hosted Checkout page, you will redirect the user for payment and wait for the use to return to your site or for a webhook event to hit.

2. Creating an Order

For the white label card processing solution only.
Process the payment with the Card Processing API by using the Create Wallet Order endpoint.
Use the returned reservation from step #1 as the reservation Id parameter for card processing.

🚧

Note

This implementation is more complex and requires you to have additional controls to ensure card data security (or to outsource this to a 3rd party). See our Spreedly guide for a potential solution.

{
    "debitCard": {
        "number": "4111111111111111",
        "year": 2023,
        "month": "10",
        "cvv": 555
    },
    "amount": 50,
    "sourceCurrency": "USD",
    "trigger3ds": true,
    "destCurrency": "BTC",
    "dest": "bitcoin:2NGQHChFMFaHbRAayBQKN93CZKEoRePoSWY",
    "referrerAccountId": "AC_JVGFSWYQH4B",
    "givenName": "daffy",
    "familyName": "duck",
    "email": "[email protected]",
    "phone": "+18052883333",
    "reservationId": "9N7Z6CE6MBC9U96ARVB3",
    "address": {
        "street1": "23432 Balboa St",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": 94105,
        "country": "US"
    }
}

After you've created the order, you will receive the id of the order in the response. Also note the status and authCodesRequested parameters.

{
   "id":"WO_PQAG8JHTA2F",
   "createdAt":1595539060000,
   "owner":"account:AC_RW4FHEJPCHW",
   "status":"RUNNING_CHECKS",
   "orderType":"INTERNATIONAL",
   "sourceAmount":10.0,
   "purchaseAmount":9.31,
   "sourceCurrency":"USD",
   "destCurrency":"BTC",
   "transferId":null,
   "dest":"bitcoin:tb1q6yn0ajs733xsk25vefrhwjey4629qt9c67y6ma",
   "email":"[email protected]",
   "authCodesRequested":false,
   "paymentMethodName":"Visa ending 1111",
   "accountId":"AC_RW4FHEJPCHW"
}

Example shows the Create Transfer endpoint data.

3. Check for Auth Codes

While the order status = RUNNING_CHECKS and authCodesRequested is true, poll the Get Authorization endpoint to determine which auth codes are required.

By default Wyre requires two authentication codes if authCodesRequested is true :
CARD2FA - A 6 digit code that's added immediately to the end user's bank account. This code is usually displayed under Temporary Authorizations in the user's bank or credit card account online.
SMS - A 6 digit code sent to the user's mobile device.

If the auth code check gives an error 'Authorization Details Not Available' it means the order status has changed and is no longer RUNNING_CHECKS. In this case poll the order status again to get the latest status.

By setting the 'trigger3ds' to true in the Create Order request you can substitute Card2fa and SMS for 3D Secure, authentication performed by the issuing bank. In this case the auth codes check returns a Url. It is recommended that the 3D Secure url is hosted in an iframe with a minimum size of 250 x 400 to avoid popup blockers.

{
   "walletOrderId":"WO_9PUXWLZD888",
   "smsNeeded":true,
   "card2faNeeded":true
}

//endpoint:
//v3/debitcard/authorization/{WO_id}/with-redirection

{
    "walletOrderId": "WO_VYAL39RZQ4",
    "smsNeeded": false,
    "card2faNeeded": false,
    "authorization3dsUrl": "https://pay.testwyre.com/bank-authorization/WO_VYAL39RZQ4?redirectUrl=https%3A%2F%2Fwww.sendwyre.com&autoRedirect=true"
}

4. Authorizing Orders

In case the check for auth codes returned true for 'smsNeeded' or card2faNeeded', you will need to request the user to submit those values through your app on to Wyre. These auth codes must be submitted within 10 minutes and can not be tried more than 5 times, after that the order will expire.

In case of 3D Secure, redirect user to the Url provided instead of requesting SMS or Card2fa codes.

{
    "type": "ALL",
    "walletOrderId": "WO_N4WZ696WJ6",
    "sms": "000000",
    "card2fa": "000000"
}

5. Verify Order Status

For hosted Checkout implementations, parse the redirect Url for the order Id and check the order status or use the webhook event.

Example redirect Url with order Id
https://www.sendwyre.com/?accountId=user%3AUS_W9GTX3FPY8P&blockchainNetworkTx&dest=bitcoin%3A2NGQHChFMFaHbRAayBQKN93CZKEoRePoSWY&destAmount=0.00218338&fees=%7B%22BTC%22%3A0.00000492,%22USD%22%3A5%7D&orderId=WO_46VLWZYNGF&transferId=TF_V6Y6JWGA2PL

For white label implementations, or in case you don't receive the user back to your Url, use webhooks to receive status updates. See (Webhooks)(doc:webhooks) for more examples.

{
    "referenceId": null,
    "accountId": "AC_JVPFPWYQH4B",
    "orderId": "WO_TM8DBFZXT9",
    "orderStatus": "PROCESSING",
    "transferId": "TF_F69PAEJVYMQ",
    "failedReason": null,
    "error": null,
    "reservation": "RENEYND226MMB28RRJVM",
    "email": "[email protected]"
}

{
    "id": "WO_TM8DBFZXT9",
    "createdAt": 1644347383000,
    "owner": "user:US_W9GTX3FPY8P",
    "status": "COMPLETE",
    "orderType": "DOMESTIC",
    "sourceAmount": 55.26,
    "purchaseAmount": 5E+1,
    "sourceCurrency": "USD",
    "destCurrency": "BTC",
    "transferId": "TF_F69PAEJVYMQ",
    "dest": "bitcoin:mtzzXFuFLDp5RTLT678mdbYDtoyT2gQjQe",
    "authCodesRequested": true,
    "blockchainNetworkTx": null,
    "accountId": "US_W9GTX3FPY8P",
    "paymentMethodName": "Visa ending 1111"
}

Updated over 2 years ago