Guides

Card Processing Overview

The following is a guide on how you're able to use the Card Processing API to accept payments within your application.

📘

Please reach out to [email protected] to enable this

Please reach out to the sales team to enable this feature within your account.

1.) CREATE WALLET ORDER RESERVATION

After getting all set up, you'll need to create a Wallet Order Reservation ID for a wallet order. 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.

2.) CREATE WALLET ORDER

Use the code example (top of the page) to process the payment with the Card Processing API.

Use the returned reservation from step #1 as the reservationId param for card processing.

3.) GET ORDER ID and AUTH CODES

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"
}

4.) AUTHENTICATION CODES STATUS

While the order status = RUNNING_CHECKS, poll the Card Authorize endpoint to determine if authCodesRequested is true. authCodesRequested may return true or false.

🚧

Auth Codes Checks

When the wallet order status is different than RUNNING_CHECKS the Card Authorize endpoint (smsNeeded and card2faNeeded) should be ignored.

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

5.) POSTING AUTHENTICATION CODES

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.

You will need to confirm the codes that are requested. If the Authentication codes are not provided, the order will expire - the current expiration time is 10 minutes. When building your UI, you need to make it a real-time experience.

The GET request is only available until codes are still valid. After that, if you try to get authorization information in this endpoint we throw an error, check Card Exceptions]. The current limit of attempts to specify the code is 5 times. After this, you will receive back an error and the order will expire.

You must provide the codes back in the following endpoint Card Authorize:

{
   "type":"SMS", 
   "walletOrderId":"WO_Y74E8FXVWJ2",
   "reservation":"NHEA3UYXEXCUX4Y2HG78",
   "sms":"000000",
   "card2fa":"000000"
}

The node type must be either SMS, CARD2FA or ALL. When SMS the node sms is mandatory, when CARD2FA the node card2fa is mandatory, when ALL both sms and card2fa are mandatory.

Response

{
  "walletOrderId":"WO_DX6B3UAVN8B",
  "success":true
}

When any code failed due to any reason (max attempts, time expiration...) the order will also fail and card refunded. Failed orders cannot be resumed. These codes' needs might change at any time and based on the buyer's info.

6.) VERIFY ORDER AUTHORIZATION

Keep polling Wallet Order Details until the order's status is PROCESSING or COMPLETE.

This is a publicly accessible endpoint:
https://api.sendwyre.com/v3/orders/:orderId

You can also receive updates via Webhooks, contact our sales team at [email protected] to set up your webhook configuration.

7.) TRACK WALLET ORDER

Once the transferId is returned it means the order was accepted and the transfer (blockchain transaction) is in progress.

To track its progress please check the transfer tracking documentation here: Track Wallet Order

🚧

Test Data

You should provide your own test dummy data. Do not use the data in the samples.

📘

Wyre Referral Agreement

Your application should allow end users the ability to accept Wyre's User Agreement during the checkout process. This can function as a checkbox with a link to the agreement.

Example:
☑️I accept Wyre's User Agreement.

If you would like to build your custom checkout flow using the API, but keep your PCI compliance requirements limited to the minimal level, Wyre's Card Processing API is the ideal solution. Like all of our cards products, Wyre only supports Debit Cards from MasterCard and Visa at the moment. If you'd like Credit Card supported, please reach out to our sales team at [email protected].

Limitations and Considerations

There are certain limitations on the types of cards that can be processed. We currently process through the Visa and Mastercard networks only.

We cannot process:

  • Pre-Paid Debit or Gift Cards
  • Cards issued by a neo/virtual bank
  • Unsupported networks

There are also additional considerations for processing credit cards vs. debit cards. Many credit card issuers will consider crypto purchases the same as a cash advance. The issuing bank may charge your user additional cash advance fees for their crypto purchases through Wyre. You may want to limit processing to debit cards only, or fully disclose the possibility of additional fees levied by the credit card issuer.

Errors

View the list of Card Exceptions. The Wallet Order Details endpoint is also a source for providing error messaging related to a particular order.