API Reference

White-Label Card Processing

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

📘

Note, additional approval required for this functionality.

Please reach out to the sales team to request approval for this implementation. Our Compliance and Risk team have additional requirements for partners that manage card data security themselves.

🚧

Wyre Referral Agreement

Your application must 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.

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

Process the payment with the Card Processing API by using the Create Wallet Order endpoint.

Use the returned reservation from step #1 as the reservationId param for card processing. Note, default authorization is SMS and card2fa, to invoke 3D Secure use the body parameter 'trigger3ds' with the Create Wallet Order endpoint.

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. Check Auth Code Requirements

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

🚧

Auth Codes Checks

When the wallet order status is different than RUNNING_CHECKS the Get Authorization endpoint (smsNeeded and card2faNeeded) should be ignored.
When using 3D Secure, the authorization3dsUrl will be populated, redirect the user there for authentication with their issuing bank (requires trigger3ds = true in the body of Create Order).

Wyre may require the following authentication codes:
CARD2FA - A 6 digit code that's added immediately to the end user's bank account.
SMS - A 6 digits sent to the user's mobile device.
3DS: A redirect Url where 3D Secure will be performed by the issuing bank. (Requires trigger3ds = true in the body of Create Order).

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

5. Submit Authorization Codes

Provide the codes back in the following Submit Authorization endpoint:

{
   "type":"ALL", 
   "walletOrderId":"WO_Y74E8FXVWJ2",
   "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 Get Wallet Order 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

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 Get Wallet Order Full endpoint is also a source for providing error messaging related to a particular order.