Guides

White Label Card Processing

Suggest Edits

Wyre offers our partners the benefit of implementing the functionality of our card processing API while maintaining their own UX/UI. This is available to partners that fulfill the specific requirements in the box below. The following is a guide on how to implement white label card processing if those requirements are met.

Key Requirements

🚧

Card Processing Requirements

PCI Compliance
If you choose this option you must demonstrate your PCI compliance to Wyre. This typically means you use a third party to handle card data securely. See our integration to Spreedly guide in the resource section for an easy solution.

User Agreement Disclosure
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, see our example from Wyre Checkout at the bottom of this guide.

Basic example:
☑️I accept Wyre's User Agreement.

👍

3D Secure Now Required

Wyre now requires 3D Secure authentication on each card payment (wallet order). Use 'trigger3ds' in Create Order to initiate 3D Secure. This improves user experience and helps us prevent fraud.

Create 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 orders to data in your own database. Reservations are good for one hour. Learn more about Wallet Order Reservations.

For the best user experience, use the autoRedirect parameter in Create Wallet Order Reservation to ensure the user returns immediately to your site or app after authentication is completed.

{
    "referrerAccountId": "AC_JVPFPWYQH4B",
    "destCurrency": "ETH",
    "sourceCurrency": "USD",
    "redirectUrl": "https://www.sendwyre.com",
    "autoRedirect": true,
    "amount": "25",
    "country": "US",
    "dest": "ethereum:0xDf9f41c57f12b591671E0f02F41121CecE079e2E"
}

Create 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. 

{
    "debitCard": {
        "number": 4111111111111111,
        "year": 2023,
        "month": 10,
        "cvv": 123
    },
    "amount": 100,
    "sourceCurrency": "USD",
    "amountIncludeFees": true,
    "trigger3ds": true,
    "destCurrency": "USD",
    "dest": "account:AC_JVPFPWYQH4B",
    "referrerAccountId": "AC_JVPFPWYQH4B",
    "givenName": "tim",
    "familyName": "cook",
    "email": "[email protected]",
    "phone": "+14152887111",
    "reservationId": "9FPC2E9M96U7VPXRYG7G",
    "address": {
        "country": "US",
        "state": "WA",
        "city": "Kingston",
        "postalCode": "98346",
        "street1": "9053 NE Leprechaun Ln",
        "street2": ""
    }
}

Authentication

After you've created the order, you will receive the id of the order in the response an initial status of RUNNING_CHECKS.

Redirect the user to the authenticationUrl. This will open the Authentication Widget, which performs:
• Device Fingerprinting
• IP Collection
• Checks if there is a need of 3DS, and if yes, it redirects the user to the 3DS page

Once the user has navigated to the Auth Url and completed the flow, the order status from RUNNING_CHECKS to PROCESSING.

{
    "id": "WO_ZVZN6TEXUF",
    "createdAt": 1667323209315,
    "owner": "account:AC_PF79YUXMP43",
    "status": "RUNNING_CHECKS",
    "orderType": "DOMESTIC",
    "sourceAmount": 120.00,
    "purchaseAmount": 115.00,
    "sourceCurrency": "USD",
    "destCurrency": "USD",
    "transferId": null,
    "dest": "account:AC_JVPFPWYQH4B",
    "authCodesRequested": false,
    "blockchainNetworkTx": null,
    "authenticationUrl": "https://pay.testwyre.com/authentication/WO_ZVZN6TEXUF?accountId=AC_RYMU7EZFFJY&reservation=428X8HF8ZQP8EUU6WGVJ&customerId=AC_PF79YUXMP43&autoRedirect=true&redirectUrl=https%3A%2F%2Fwww.sendwyre.com&failureRedirectUrl=&flow=CARD_API",
    "accountId": "AC_PF79YUXMP43",
    "paymentMethodName": null
}

For legacy implementations not using 3D Secure:

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 while 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 Submit Authorization endpoint:

{
   "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, etc.) 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.

Verify Order Status

Refer to Card Processing Overview for the Order Status diagram.

Once an order reaches 'PROCESSING' it means the card payment was successful, and a transferId will be created. This transfer represents the delivery of crypto and indicates that process is underway.

Order status updated to 'COMPLETE' means the crypto has been delivered successfully. Settlement times depend on network activity and are subject to change. For purely fiat payments the order will move immediately from Processing to Complete.

Keep polling Get Wallet Order and/or listen to Webhooks until the order's status is PROCESSING or COMPLETE.

You can also track its progress here: Track Wallet Order.

For manual look up we provide a publicly accessible endpoint:

https://api.sendwyre.com/v3/orders/:orderId

{
    "referenceId": null,
    "accountId": "AC_JVPFPWYQH4B",
    "orderId": "WO_DU46EN96PM",
    "orderStatus": "COMPLETE",
    "transferId": "TF_NMNN38VVYAT",
    "failedReason": null,
    "error": null,
    "reservation": "QLYWHUEJBQWMWCNJ26LY",
    "email": "[email protected]"
}

If you supplied a redirectUrl Wyre will append information to that Url allowing you to query the order for useful information, including order status, amounts and network transaction Ids.

https://www.sendwyre.com/?accountId=AC_VMHJX9GBLEW&authCodesRequested=true&authenticationUrl&blockchainNetworkTx&createdAt=1660335812000&dest=account%25253AAC_JVPFPWYQH4B&destCurrency=USD&id=WO_TGHNFDQ23Z&ok=true&orderType=DOMESTIC&owner=account%25253AAC_VMHJX9GBLEW&paymentMethodName=Visa%252520ending%2525201111&purchaseAmount=100&sourceAmount=110&sourceCurrency=USD&status=PROCESSING&transferId=TF_X7WBTN2ZEGQ

Sample User Agreement Disclosure

Your app must allow users to agree to Wyre terms and conditions at point of sale, as shown in the example here presented by Wyre Checkout.

410

Updated about 2 years ago