openapi: 3.0.0
info:
  x-logo:
    backgroundColor: '#FAFAFA'
    url: docs_logo.png
  title: xMoney for Developers
  description: "Welcome to the xMoney documentation for Developers. Here you will find\neverything you need to start accepting crypto payments in your online store\nor website easily with xMoney.\n\n\n# Basics\n\nIn this section you can find a set of concepts that will help you understand\nhow xMoney handles payments, so that you can integrate our payment method\nwithout any trouble.\n\n## 0. Before you start\n\nBe aware xMoney Payments have the following limitations:\n\n> ⏰ Our payment confirmation can take **up to 2h**;\n\n> \U0001F30D Our Payment Widget is only available in **English**.\n\n\n## 1. Checkout process\n\nOur payment flow is **asynchronous**; the customer chooses\nthe cryptocurrency and issue a transaction in the respective blockchain,\nsending the requested funds to the address we provided.\n\nOnce we detect the pending transaction, which usually happens in a matter of\nseconds, we recognize the payment and redirect the user to the merchant\nsuccess callback URL.\n\nUpon confirmation of the transaction, which can take up to 2 hours, we send\na notification to the merchant store or website via a [webhook](#section/Basics/5.-Webhooks).\n\nIn more detail, this flow has 6 stages:\n\n<div style=\"max-width: 650px; margin: 28px auto;\">\n  <img src=\"diagram.png\" alt=\"Checkout process diagram\" />\n</div>\n\n1. [**Merchant**] On checkout, the merchant system sends the order details to\n   create it on our server, getting a `redirect_url` in the response\n   (see [the create order endpoint](https://docs.api.crypto.xmoney.com/#operation/createOrder)).\n2. [**Merchant**] Redirects users to the provided URL, which shows them the\n   xMoney Payment widget.\n3. [**xMoney**] Users pay for the order, seeing a \"Payment Complete\"\n   message. xMoney also sends them an email with the detected payment\n   details. This completes the user interaction.\n4. [**xMoney**] Redirects the customer back to the `return_url` provided\n   when the order was created.\n5. [**xMoney**] It takes some time to confirm transactions (minutes or hours,\n   depending on the blockchain). Once confirmed, xMoney sends an HTTP\n   request to the Merchant system notifying the payment was received.\n6. [**Store**] Verifies and validates the request, and, if valid, finalizes\n   the order.\n\n\n## 2. Try our flow\n\nThe best way to learn about what we do is by trying it out yourself. For\nthis, we recommend you to use [MultiversX Devnet wallet](https://devnet-wallet.multiversx.com/unlock/).\nTo use it, you will need to get Devnet funds (or \"fake\" EGLD, notice Devnet instead of Testnet).\nAfter creating your wallet, on the left menu, find section \"Tools\". Below, click on \"Faucet\".\nThen click \"Request tokens\". This should get you 5 xEGLD (which is the \"fake\" EGLD you will need to test in Devnet).\nIf that faucet is not working, you can try [this one](https://r3d4.fr/faucet) (don't forget to choose Devnet,\nas for MultiversX, it is the network we use for testing).\n\n![Elrond_devnet_wallet](1_egld.png)\n\nYou can also use [MetaMask](https://metamask.io/) with some fake ETH, just make sure to change to the Sepolia Testnet, which\nis what we use in our sandbox environment.\n\nWhen you are ready, go to our [Sandbox online store](https://demo.crypto.xmoney.com/)\nand give it a spin by selecting an item and proceeding to checkout.\nChoose the xMoney payment method.\nOnce you proceed to the payment, you will see xMoney Payment Widget.\n\nConfirm prefilled email or fill in the one you want to use.\n\n![xMoney_payment_widget_email_constent](widget/01–widget–email_consent.png)\n\n Select Pay with another wallet.\n\n![xMoney_payment_widget_method_selection](widget/02–widget–method.png)\n\nSelect the EGLD (MultiversX) currency.\n\n![xMoney_payment_widget_currency_selection](widget/03-widget-currency-selection.png)\n\nSelect MultiversX network.\n\n![xMoney_payment_widget_network_selection](widget/04-widget-chain-selection.png)\n\nThe widget will then show you a QR Code with the\npayment details. Copy the address and amount.\n\n![xMoney_payment_widget_qr-code](widget/05-widget-qr-code.png)\n\nOpen Elrond wallet and send the amount in xEGLD to the provided address.\n\n![Elrond_wallet_filled](2_egld.png)\n\nWait some seconds, and the widget should change to show the payment is\ncomplete.\n\n![xMoney_payment_widget_completed](widget/06–widget–wuccess.png)\n\nFor EGLD, the payment is complete because transactions are confirmed very\nfast. For other cryptocurrencies, it can take some minutes to confirm. Either\nway, the confirmation notification will we delivered to the merchant server,\nvia [webhook](#section/Basics/5.-Webhooks).\n\n\n## 3. Build the order\n\nAssuming you now have a clear understanding of the flow, let's integrate\nyour system.\n\n\n### 3.1. Sandbox and Production\n\nIn addition to the real-world payment processing environment - Production, xMoney offers\ndevelopers an environment where they can test their integration using\nnot-so-valuable test money. We call this environment Sandbox.\n\nThe two environments are identical for most of the time, differing only in\nthat Production uses blockchains mainnets, and Sandbox uses the respective\ntestnets.\n\nHowever, please note that some currencies may not available in Sandbox\ndue to the unavailability of their testnets. For example,\nLightning Network cannot be used to test Bitcoin transfers in Sandbox,\nbut is always available for testing in Production.\n\nWe also release new features to Sandbox a bit before them reaching\nProduction, but this usually happens in a couple of hours.\n\nDepending on which environment they want to target, developers must choose\nthe appropriate hostname to target their requests. Production uses the\n`crypto.xmoney.com` domain, whereas Sandbox uses the `sandbox.crypto.xmoney.com` domain.\n\n\n### 3.2. Sign up for Sandbox\n\nTo use our Sandbox environment\n[first you need a merchant account](https://merchants.sandbox.crypto.xmoney.com/onboarding/sign-up).\nRemember Production is a separate environment, your real merchant account\nwon't exist in Sandbox (but here you can have many).\n\n![Merchant_Dashboard_signup](md/01-md-sign_up.png)\n\n\n### 3.3. Authentication\n\nYou must then generate credentials for your store, which can be done through\nyour xMoney Merchant Dashboard. In there, go to the Integrations section, choose _Custom_ and click on the _Generate Credentials_ button.\n\n![Merchant_dashboard_organization](md/02-md-integrations.png)\n\nYou’ll then be shown the `API Key` and `Webhooks Secret` for your store.\nThis information will not visible afterwards, make sure to save it.\n\n![Merchant_dasboard_new_credentials](md/03-md-credential_confirmation.png)\n\n\n### 3.4. Creating the order\n\nOrders are base concept to process payments in xMoney. To process a payment\nthe system must first call the\n[create order endpoint](https://docs.api.crypto.xmoney.com/#operation/createOrder).\n\nThe response will then contain a URL to which users must be redirected. When\nthe payment is processed xMoney redirects the user back to the system, using\nthe URLs provided.\n\n\n### 3.5. Going into production\n\nAll tests went good and you want to move into production? To create a `production` account [go here](https://merchants.crypto.xmoney.com/).\nYou will have to generate your production API Key and Webhook secret in the Integrations page.\nIf you need to add more users, please <a href=\"mailto:support@xmoney.com?subject=Need more users\">let us know</a> and we will add them manually to the same Organization.\n\n\n## 4. Checkout suggestions\n\nTo increase conversions on the checkout page, we suggest you to add the following:\n- **Payment method name**: “Pay with Crypto” or xMoney — Pay with Cryptocurrencies” (if it’s not possible to add the xMoney logo)\n\n  Have in mind the correct way to spell \"xMoney\":\n\n  <img alt=\"How to write xMoney\" style=\"max-width: 350px\" src=\"spelling.png\" />\n- **Description/Instructions**: “You will be redirected to the xMoney payment widget compatible with any major crypto wallets. It will allow you to pay for your purchase in a safe and seamless way using Bitcoin, Ethereum, Tether or a number of other currencies. [What is xMoney?](https://xmoney.com/)”\n- **xMoney checkout logo**: Download the logos [here](https://drive.google.com/drive/folders/1g3gpQ72kum3VwT0oVSJkK0iQOdjdgnwK?usp=share_link).\n\nExample with the xMoney logo:\n\n<img alt=\"Checkout with xMoney logo\" style=\"max-width: 500px\" src=\"checkout-logo.png\" />\n\nExample without the xMoney logo:\n\n<img alt=\"Checkout without xMoney logo\" style=\"max-width: 500px\" src=\"checkout-no_logo.png\" />\n\n\n## 5. Webhooks\n\nMerchant systems can be notified of events in the xMoney platform through\nwebhooks. At the moment these events include:\n\n- Confirmation of the order payment;\n- Cancellation of the order.\n\nThe URL to use for these webhooks is defined by the `callback_url` field\nwhen creating an order.\n\nAll webhook requests are expected to respond with HTTP status 2xx in case\nof success. Any other status code, or the lack of a response, will be\nconsidered a failure. In that case xMoney will retry up to 15 times with an\nexponential back off following a Fibonacci sequence -- first retry happens\nafter 1 minute, second happens 2 minutes after the first one, third happens\n3 minutes after the second one, etc.\n\nAll requests sent by xMoney to the provided URL are signed for validation\nusing the `Webhooks Secret` generated (see [3.3\nAuthetication](#33-authentication)).\n\nWhen using our [integrations](#section/Integrations), webhooks are set and\nvalidated automatically as part of the order payment flow. For custom\nintegrations we make available [libraries](#section/Libraries) able to\nvalidate the requests.\n\nFor manual validation instructions, and further technical details, check\nthe [Webhooks](https://docs.api.crypto.xmoney.com/#tag/Webhooks) section in the\n[xMoney API](https://docs.api.crypto.xmoney.com) documentation.\n\n\n\n# Integrations\n\nxMoney develops and maintains plugins for some of the most popular\ne-commerce solutions.\n\n<table>\n  <thead>\n    <tr>\n      <th colspan=\"2\">Platform</th>\n      <th></th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td rowspan=\"2\">\n        <img alt=\"Magento logo\" src=\"https://user-images.githubusercontent.com/1558992/70810396-97bc2080-1dbb-11ea-8724-fb1ed032da18.png\">\n      </td>\n      <td>\n        Magento 1\n      </td>\n      <td>\n        <a href=\"https://github.com/utrustdev/utrust-for-magento1\">\n          Download\n        </a>\n      </td>\n    </tr>\n    <tr>\n      <td>\n        Magento 2\n      </td>\n      <td>\n        <a href=\"https://github.com/utrustdev/utrust-for-magento2\">\n          Download\n        </a>\n      </td>\n    </tr>\n    <tr>\n      <td>\n        <img alt=\"OpenCart logo\" src=\"https://user-images.githubusercontent.com/1558992/96702918-26a9aa00-138a-11eb-9cb6-cb26e93e09c7.png\">\n      </td>\n      <td>\n        OpenCart 3\n      </td>\n      <td>\n        <a href=\"https://www.opencart.com/index.php?route=marketplace/extension/info&extension_id=40369\">\n          OpenCart marketplace\n        </a>\n        or\n        <a href=\"https://github.com/digito-solutions/Plugin-Utrust-Opencart-3\">\n          Download\n        </a>\n      </td>\n    </tr>\n    <tr>\n      <td>\n        <img alt=\"Payrexx logo\" src=\"https://user-images.githubusercontent.com/1558992/107674377-d33bce80-6c8e-11eb-8bea-020eea13ade4.png\">\n      </td>\n      <td>\n        Payrexx\n      </td>\n      <td>\n        <a href=\"https://gist.github.com/xmoneycrypto/5abec58b80c6bf4d6fd19cf3229c3608\">\n          Instructions\n        </a>\n      </td>\n    </tr>\n    <tr>\n      <td rowspan=\"2\">\n        <img alt=\"PrestaShop logo\" src=\"https://user-images.githubusercontent.com/1558992/70810397-97bc2080-1dbb-11ea-815a-32f389f3b0c3.png\">\n      </td>\n      <td>\n        PrestaShop 1.6\n      </td>\n      <td rowspan=\"2\">\n        <a href=\"https://github.com/utrustdev/utrust-for-prestashop\">\n          Download\n        </a>\n      </td>\n    </tr>\n    <tr>\n      <td>\n        PrestaShop 1.7\n      </td>\n    </tr>\n    <tr>\n      <td>\n        <img alt=\"Weasy logo\" src=\"https://user-images.githubusercontent.com/1558992/130259300-fe4ea5eb-dd01-4af8-a588-3888b10de09e.png\">\n      </td>\n      <td>\n        Weasy\n      </td>\n      <td>\n        <a href=\"https://gist.github.com/xmoneycrypto/0092f187e2d84b226f5bb8830f31ca0e\">\n          Instructions\n        </a>\n      </td>\n    </tr>\n    <tr>\n    <tr>\n      <td>\n        <img alt=\"WHMCS logo\" src=\"https://user-images.githubusercontent.com/1558992/104025764-03d6a700-51bd-11eb-9f69-63ed865bfda7.png\">\n      </td>\n      <td>\n        WHMCS\n      </td>\n      <td>\n        <a href=\"https://marketplace.whmcs.com/product/5733-utrust-for-whmcs\">\n          WHMCS marketplace\n        </a>\n        or\n        <a href=\"https://github.com/utrustdev/utrust-for-whmcs\">\n          Download\n        </a>\n      </td>\n    </tr>\n    <tr>\n      <td>\n        <img alt=\"WooCommerce logo\" src=\"https://user-images.githubusercontent.com/1558992/70810398-9854b700-1dbb-11ea-8127-d926450a8e62.png\">\n      </td>\n      <td>\n        WooCommerce\n      </td>\n      <td>\n        <a href=\"https://wordpress.org/plugins/utrust-for-woocommerce/\">\n          Wordpress marketplace\n        </a>\n        or\n        <a href=\"https://github.com/utrustdev/utrust-for-woocommerce\">\n          Download\n        </a>\n      </td>\n    </tr>\n  </tbody>\n</table>\n\n**Is your platform missing from this list?**\n\n<a href=\"mailto:integrations@xmoney.com?subject=Missing platform integration\">Let us know</a> so we can consider it in our\ndevelopment roadmap.\n\nAlternatively, use our [API documentation](https://docs.api.crypto.xmoney.com/) to\nbuild the integration you need and join forces with us to foster an active\nopen-source community around xMoney.\n\n\n# Libraries\n\n<table>\n  <thead>\n    <tr>\n      <th>Language</th>\n      <th>Repository</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>PHP</td>\n      <td>\n        <a href=\"https://github.com/utrustdev/utrust-php\">\n          utrust-php\n        </a>\n      </td>\n    </tr>\n    <tr>\n      <td>CFML</td>\n      <td>\n        <a href=\"https://github.com/GaryStanton/UtrustCFML\">\n          UtrustCFML (maintained by Gary Stanton)\n        </a>\n      </td>\n    </tr>\n    <tr>\n      <td>Typescript</td>\n      <td>\n        <a href=\"https://github.com/utrustdev/utrust-ts-library\">\n          utrust-ts-library\n        </a>\n      </td>\n    </tr>\n  </tbody>\n</table>\n\n**Is your language missing from this list?**\n\n<a href=\"mailto:integrations@xmoney.com?subject=Missing language library\">Let us\nknow</a> so we can consider it in our development roadmap.\n\nAlternatively, use our [API documentation](https://docs.api.crypto.xmoney.com/) to\nbuild the library you need and join forces with us to foster an active\nopen-source community around xMoney.\n\n\n# APIs\n\nThe xMoney platform provides public APIs that you can use to build your\nown tools around our ecosystem.\n\nFor more details, check the [xMoney API\nReference](https://docs.api.crypto.xmoney.com).\n"
paths: false
