Overview

Home

Welcome to Crypto.com Pay for Business! Here you can find out how you can adopt the best way to accept cryptocurrency payments.

Crypto.com Pay for Business is a product of Crypto.com Pay, which utilises Crypto.com App, Crypto.org Chain, and Cronos to be a high-performing payment solution. This enables the transaction flows between crypto users and merchants seamless, cost-efficient, and secure.

Accepting Payments

Payment Methods

Crypto.com Pay for Business supports payments using Crypto.com App and other cryptocurrency wallets.

A Crypto.com App user can simply use the Crypto.com App (available on iOS and Android) to scan the QR code, select their preferred payment cryptocurrency and complete the transaction. Please refer to this FAQ article for the screen examples.

Customers can also pay with other cryptocurrency wallets other than Crypto.com App, such as Crypto.com DeFi Wallet, MetaMask, WalletConnect or Ledger, etc to pay. Please note that the customers will have to bear the network fees when they choose to pay using methods other than Crypto.com App.

Checkout Payment Flow

Please check out this video and this FAQ article for the payment experience.

When creating payments for your customers to pay, you can specify the payment amount (your products' listed price) in any supported fiat currencies (e.g. 1,000 USD) / supported cryptocurrencies (e.g., 0.03 ETH). The Crypto.com Pay payment page will provide your customers with different cryptocurrency payment options. It will also determine the amount required in customer selected cryptocurrency (e.g. 250 CRO).

Once paid, the payment is captured on the merchant's end, the cryptocurrency will then be converted and credited into your wallet balance. You can select the merchant default currency from one of the Payout currencies we support.

Subscription Flow

The Crypto.com Pay subscription payment page will guide your customers to select the cryptocurrency to pay and approve the subscription. Once it is approved, payment of the first billing period will be collected right away. In subsequent billing periods, payments will be automatically created and collected.

The subscription payment amounts can be specified in any supported fiat currencies (e.g. 1,000 USD) / supported cryptocurrencies (e.g., 0.03 ETH). Once the payment of each period is captured, the cryptocurrency will be converted and credited into your wallet balance.

Both you and your customers can cancel the subscription anytime.

Subscription is only available to customers using Crypto.com App.

Payment Currencies

Crypto.com Pay for Business currently accepts the following cryptocurrencies:

• Cronos (CRO)
• Bitcoin (BTC)
• Ethereum (ETH)
• Dogecoin (DOGE)
• Stable Coins (USDC)
• Other tokens supported by Crypto.com App and Crypto.com DeFi Swap

Please refer to this FAQ article for the full list of cryptocurrencies supported.

For information on available payout currencies for merchants, please see Payout.

Fees

Crypto.com Pay for Business has no transaction fee. For each payment from customers, merchants are guaranteed to receive the fiat currency amount they specified. The amount will be credited into the balance of the merchant account and can be withdrawn anytime.

When merchants request payout, a payout fee is applied. Please see Payout for more information.

Pay Rewards

Crypto.com Pay offers a Pay Rewards program to early or selected merchants. When customers pay using Crypto.com App and CRO, a CRO rebate will be provided to the customers. If the customers have eligible CRO stakes in their Crypto.com accounts, they can even enjoy 2x of the normal rebate rate.

Once you logged into the Merchant Dashboard, you can see the Pay Rewards percentage that your customers can earn.

Merchants should use the Promotion Banners to promote the rebate to their customers.

For information on Crypto.com Pay Rewards, please visit this FAQ article.

Refund

Merchants can refund all payments received either partially or in full.

For customers who pay using Crypto.com App, the refund will be sent back to their App account automatically. A preferred refund currency setting is available in App so that customers can select the cryptocurrency they want to receive for refunds.

For customers who pay using other cryptocurrency wallets, the payment page requires them to input their email addresses when they pay. When a refund is issued, a refund claim link and instruction will be sent to the email address provided for the customer to claim the refund. Subject to the refund method selected, a blockchain fee may be deducted from the refund amount.

Unresolved Payments

For customers who pay using other cryptocurrency wallets, the payment can be overpaid or underpaid. This is because there is no payment amount input check, and the cryptocurrency exchange rate could be updated when customers made the payment. The payment can also be late if the funds did not reach the provided wallet address in time.

If the payment is overpaid, the overpaid portion (with blockchain fee deducted) will be rebounded to the customer. On the merchant's end, the payment is still considered to be captured successfully.

If the payment is underpaid or late, the whole payment (with blockchain fee deducted) will be rebounded to the customer.

Similar to refund, a rebound fund claim link and instruction will be sent to the customer email address provided, so they can claim the rebound fund.

If the payment is sent using a cryptocurrency or network not supported by Crypto.com Pay, the funds will not be refunded or rebounded.

Merchant can navigate to Merchant Dashboard -> Payments -> Unresolved page to view these transactions. The claim links of the rebound fund can be found in the detailed view of each unresolved transaction.

Underpayment Threshold

To improve the user experience of on-chain payments and reduce the unnecessary network fees, merchants can decide a threshold of accepting payments from other cryptocurrency wallets even when those are underpaid.

The underpayment threshold can be set up in an absolute or relative (percentage) manner. Payments will be captured when they are within any of these two thresholds. Customers will not see these thresholds.

When a payment is underpaid and captured, the amount will be credited to the merchant account on a pro-rata basis. For example, if a customer paid 98 USDC for a payment with the amount of 100 USD, and it is within the threshold, then 98 USD will be credited to the merchant account.

Merchant can navigate to Merchant Dashboard -> Settings -> Payment page -> Underpayment Threshold to set up. This option is only enabled when the other cryptocurrency wallets payment option is enabled.

Payments paid using Crypto.com App will not be underpaid.

Merchant Acquirers

We welcome acquirers to help Crypto.com Pay onboard more merchants. Please contact [email protected] if you are interested.

Acquirers need to provide simple business information for each sub-merchant under their account, including an ID that the acquirer uses to refer to that sub-merchant.

When creating payments, the ID of the sub-merchants is required. It can also be retrieved back in our payment and refund APIs.

Creation of sub-merchants can be done through our Sub-merchant API or in the Merchant Dashboard.

Payouts

Crypto.com Pay for Business charges a payout fee for all payout settlements. A minimum blockchain transaction fee can be applied for very small settlement amount. Please login to Merchant Dashboard and check the payout page for more details.

For fiat currencies payout, a transmittance fee of may be applied depending on the intermediaries between your bank and our fiduciary partners. These are third parties that handle the wire transfer across countries and are outside of our control. Our fiduciary partners facilitate transfers to most of the international banks around the world.

Payout Currencies

Fiat Currencies

* Bank account must be in SEPA countries. See list of SEPA countries here.

For fiat currencies payout, a transmittance fee may be applied depending on the intermediaries between your bank and our fiduciary partners. These are third parties that handle the wire transfer across countries and are outside of our control. Our fiduciary partners facilitate transfers to most of the international banks around the world.

Cryptocurrencies

A minimum blockchain transaction fee can be applied for small settlement amount. Please login to Merchant Dashboard and check the payout page for more details.

Pay Catalogue

As a Crypto.com Pay merchant, you’re able to take advantage of the world’s growing crypto adoption by reaching our over 50 million strong user base.

We have built several features to help our merchants succeed. Among them is the Pay Catalogue - a directory of shops that Crypto.com App users can easily browse and make purchases from every day.

You can go to Merchant Dashboard -> Settings -> Business -> Shop Information to submit your shop listing for the Pay Catalogue. Please refer to this FAQ article for the submission guidelines.

Each listing in the Pay Catalogue will undergo a review process. To be listed, your shop must also be compatible with different devices (especially mobile) and include our Promotion Banners.

Integration Guides

Checkout - Button SDK

Generate the Crypto.com Pay Button and embedded it on your website. Once the button is clicked, there will be a popup for customers to complete payment.

You will be able to see this on your checkout page:

You can always take a look at the Crypto.com Shop and see what it is like in the real world.

Get started by picking one of the following integration approaches, as simple as that!

Approach 1: Frontend and Backend Integration

Step 1: Register Crypto.com Pay Developer Access

Sign up for a Crypto.com Pay account, if you don't already have one.

Once you have access to the Crypto.com Pay Merchant Dashboard, You will be able to generate a secret key and publishable key pair. You should use the publishable key in the Crypto.com Pay SDK and the secret key when you directly interact with the Crypto.com Pay API.

Step 2: Add the Crypto.com Pay SDK Script

Add the script

<body>
  <script src="https://js.crypto.com/sdk?publishable-key=YOUR_PUBLISHABLE_KEY_PLACEHOLDER"></script>
</body>

Add the following script to your web page. Replace the YOUR_PUBLISHABLE_KEY_PLACEHOLDER with your Publishable Key.

Step 3: Create a Payment

Create payment

curl https://pay.crypto.com/api/payments \
  -u YOUR_SECRET_KEY_PLACEHOLDER: \
  -d amount=10000 \
  -d currency=USD \
  -d description="Product Name"

On server side, obtain a payment ID by creating a payment. Replace the YOUR_SECRET_KEY_PLACEHOLDER with your Secret Key. If you use curl, please note that a colon is needed after the Secret Key to prevent it from asking you for a password. A new payment is always pending to be captured. See Create a Payment for reference and the list of arguments you can pass in.

Response

{
  // Showing seclected fields only
  "id": "PAYMENT_UNIQUE_ID",
  "amount": 10000,
  "currency": "USD",
  "description": "Product Name",
  "status": "pending"
}

Step 4: Render the Crypto.com Pay Button

Render the button

<body>
  <script
    src="https://js.crypto.com/sdk?publishable-key=YOUR_PUBLISHABLE_KEY_PLACEHOLDER">
  </script>

  <script>
    var paymentId = document.querySelector('#pay-button').dataset.paymentId

    cryptopay.Button({
      createPayment: function(actions) {
        return actions.payment.fetch(paymentId)
      },
      onApprove: function(data, actions) {
        // Optional: add logic such as browser redirection or check data object content
      },
      defaultLang: 'en-US' // Optional: default language for payment page
    }).render("#pay-button")
  </script>

  <div id="pay-button" data-payment-id="PAYMENT_UNIQUE_ID"></div>
</body>

Add a container element on your page and render the Crypto.com Pay button in it. Also pass the Payment ID created in Step 3 into this container (attribute is data-payment-id).

Then implement the createPayment function. This function will be invoked when the customer clicks on the Crypto.com Pay button. Since you already have a Payment ID from Step 3, you just have to provide it and the SDK will not create another new payment.

Then implement the onApprove function. You should add logic here to notify your server side which perform Step 5. Once Crypto.com Pay captures the payment, the checkout window will indicate that the payment has been captured and the onApprove function will be called.

Step 5: Verify payment status

Retrieve the payment

curl https://pay.crypto.com/api/payments/PAYMENT_UNIQUE_ID \
  -u YOUR_SECRET_KEY_PLACEHOLDER: \

On server side, retrieve the payment and check whether the payment status is succeeded. See all the statuses here.

Approach 2: Frontend Only Integration

Step 1: Register Crypto.com Pay Developer Access

Sign up for a Crypto.com Pay account, if you don't already have one.

Once you have access to the Crypto.com Pay Merchant Dashboard, You will be able to generate a secret key and publishable key pair. You should be using the publishable key in the Crypto.com Pay SDK and the secret key when you directly interact with the Crypto.com Pay API .

Step 2: Add the Crypto.com Pay SDK Script

Add the script

<body>
  <script src="https://js.crypto.com/sdk?publishable-key=YOUR_PUBLISHABLE_KEY_PLACEHOLDER"></script>
</body>

Add the following script to your web page. Replace the YOUR_PUBLISHABLE_KEY_PLACEHOLDER with your Publishable Key.

Step 3: Render the Crypto.com Pay Button

Render the button

<body>
  <script
    src="https://js.crypto.com/sdk?publishable-key=YOUR_PUBLISHABLE_KEY_PLACEHOLDER">
  </script>

  <script>
    cryptopay.Button({
      createPayment: function(actions) {
        return actions.payment.create({
          currency: 'USD',
          amount: 100,
          description : 'Product Name',
          order_id: 'sample-order-id',
          metadata: {
            size: 'XL',
            color: 'black'
          }
        });
      },
      onApprove: function (data, actions) {
        // Optional: add logic such as browser redirection or check data object content
      },
      defaultLang: 'en-US' // Optional: default language for payment page
    }).render("#pay-button")
  </script>

  <div id="pay-button"></div>
</body>

Add a container element on your page and render the Crypto.com Pay button in it.

Then implement the createPayment function. This function will be invoked when the customer clicks on the Crypto.com Pay button. The action.payment.create function creates a new pending payment in the Crypto.com Pay server by providing details of the purchase as arguments. See Create a payment for reference and the list of arguments you can pass in.

Then implement the onApprove function. Once Crypto.com Pay captures the payment, the checkout window will indicate that the payment has been captured and the onApprove function will be called.

Checkout - Page Redirection

If you prefer a solution that has minimal impact to your user interface design, you may use your existing checkout interface, and redirect to Crypto.com payment page when customers submit your checkout form. Once the payment is made, the payment page will redirect back to your store to finish your order flow.

Step 1: Register Crypto.com Pay Developer Access

Sign up for a Crypto.com Pay account, if you don't already have one.

Once you have access to the Crypto.com Pay Merchant Dashboard, You will be able to generate a secret key and publishable key pair. You should use the secret key when you directly interact with the Crypto.com Pay API.

Step 2: Create a Payment

Create payment

curl https://pay.crypto.com/api/payments \
  -u YOUR_SECRET_KEY_PLACEHOLDER: \
  -d amount=10000 \
  -d currency=USD \
  -d description="Product Name"
  -d return_url="http://YOUR_WEBSITE.com/orders/123/complete"
  -d cancel_url="http://YOUR_WEBSITE.com/orders/123/fail"

On server side, obtain a payment ID by creating a payment. Replace the YOUR_SECRET_KEY_PLACEHOLDER with your Secret Key. If you use curl, please note that a colon is needed after the Secret Key to prevent it from asking you for a password. A new payment is always pending to be captured. See Create a payment for reference and the list of arguments you can pass in.

It is a must for this flow to provide return_url when creating payment. The payment returned will contain a payment_url for the next step.

Response

{
  // Showing seclected fields only
  "id": "PAYMENT_UNIQUE_ID",
  "amount": 10000,
  "currency": "USD",
  "description": "Product Name",
  "status": "pending",
  "payment_url": "https://js.crypto.com/sdk/payments/checkout/set_wallet?publishableKey=XXX&sdkMeta=YYY",
  "return_url": "http://YOUR_WEBSITE.com/orders/123/complete",
  "cancel_url": "http://YOUR_WEBSITE.com/orders/123/fail"
}

Step 3: Redirect to payment page

After creating the payment object, you will need to redirect customers to payment_url to finish the payment. After the payment is paid, it will become succeeded. The payment page will then redirect customers back to return_url (or cancel_url if there is any issue).

Step 4: Verify payment status

Retrieve the payment

curl https://pay.crypto.com/api/payments/PAYMENT_UNIQUE_ID \
  -u YOUR_SECRET_KEY_PLACEHOLDER: \

On server side of your return_url page, retrieve the payment and check whether the payment status is succeeded. See all the statuses here.

Subscription - Button SDK

Generate the Crypto.com Pay Button and embedded it on your website. Once the button is clicked, there will be a popup for customers to complete the subscription authorization and payment of first billing period.

You will be able to see this on your checkout page:

Step 1: Register Crypto.com Pay Developer Access

Sign up for a Crypto.com Pay account, if you don't already have one.

Once you have access to the Crypto.com Pay Merchant Dashboard, You will be able to generate a secret key and publishable key pair. You should use the publishable key in the Crypto.com Pay SDK and the secret key when you directly interact with the Crypto.com Pay API.

Step 2: Add the Crypto.com Pay SDK Script

Add the script

<body>
  <script src="https://js.crypto.com/sdk?publishable-key=YOUR_PUBLISHABLE_KEY_PLACEHOLDER"></script>
</body>

Add the following script to your web page. Replace the YOUR_PUBLISHABLE_KEY_PLACEHOLDER with your Publishable Key.

Step 3: Create a Product and Pricing Plan

Create product and pricing plan

curl https://pay.crypto.com/api/products \
  -u YOUR_SECRET_KEY_PLACEHOLDER: \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter monthly subscription",
    "active": true,
    "description": "Newsletter monthly subscription",
    "metadata": {
      "ref_id": "6936acde-1697-456d-95c1-0afcce047b29"
    },
    "pricing_plans": [
      {
        "amount": 1000,
        "currency": "USD",
        "active": true,
        "description": "Newsletter monthly subscription pricing",
        "interval": "month",
        "interval_count": 1,
        "metadata": {
            "ref_id": "99213a90807b"
        },
        "purchase_type": "recurring"
      }
    ]
}'

On server side, obtain a pricing plan ID by creating a product and its pricing plan. Replace the YOUR_SECRET_KEY_PLACEHOLDER with your Secret Key. See Create a Product section for the schema of product and pricing plan objects that you should pass in.

You can also use the pricing plan ID of a pricing plan you created previously.

Response

{
  "id": "89630fd4-e900-40c9-a072-758f16d9dbdd",
  "account_id": "a5b1e789-fc2b-478b-a0be-3fbbc2607563",
  "active": true,
  "description": "Newsletter monthly subscription",
  "name": "Newsletter monthly subscription",
  "metadata": {
    "ref_id": "6936acde-1697-456d-95c1-0afcce047b29"
  },
  "created_at": 1628000625,
  "updated_at": 1628000625,
  "pricing_plans": [
    {
      "id": "2506cad4-fed6-49c0-98f5-34b0bedd6891",
      "active": true,
      "amount": 1000,
      "currency": "USD",
      "interval": "month",
      "interval_count": 1,
      "purchase_type": "recurring",
      "description": "Newsletter monthly subscription pricing",
      "metadata": {
          "ref_id": "99213a90807b"
      },
      "created_at": 1628000625,
      "updated_at": 1628000625,
    }
  ]
}

Step 4: Create a Customer

Create customer

curl https://pay.crypto.com/api/customers \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ: \
  -H "Content-Type: application/json" \
  -d '{
    "ref_id": "6ded84e75449",
    "name": "John Doe"
  }'

Similarly, on server side, obtain a customer ID by creating a customer. See Create a Customer section for the schema of customer object that you should pass in.

You can also use the customer ID of a customer you created previously.

Response

{
  "id": "8e384561-d781-4868-9b66-3fb2d7a83ba5",
  "email": null,
  "ref_id": "6ded84e75449",
  "name": "John Doe",
  "created_at": 1627917897,
  "updated_at": 1627917897
}

Step 5: Create a Subscription

Create subscription

curl https://pay.crypto.com/api/subscriptions \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ: \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "8e384561-d781-4868-9b66-3fb2d7a83ba5",
    "billing_cycle_anchor": 1625943925,
    "interval": "month",
    "metadata": {
      "ref_id": "34196851011b"
    },
    "items": [
      {
        "plan_id": "2506cad4-fed6-49c0-98f5-34b0bedd6891",
        "quantity": 1
      }
    ]
  }'

With customer ID and pricing plan ID, now you can create a subscription object. You also need to provide a billing_cycle_anchor which is the starting time of your billing cycle. See Create a Subscription section for the schema of subscription object that you should pass in.

Response

{
  "id": "SUBSCRIPTION_UNIQUE_ID",
  "created_at": 1625943925,
  "currency": "USD",
  "amount": 1000,
  "current_period_end": 1628622325,
  "current_period_start": 1625943925,
  "auto_end_at": null,
  "ended_at": null,
  "cancelled_at": null,
  "interval": "month",
  "interval_count": 1,
  "live_mode": true,
  "metadata": {
    "ref_id": "34196851011b"
  },
  "note": null,
  "recipient": "Crypto.com Shop",
  "reference": null,    
  "status": "pending",
  "updated_at": 1625943925
}

Step 6: Render the Crypto.com Pay Button

Render the button

<body>
  <script
    src="https://js.crypto.com/sdk?publishable-key=YOUR_PUBLISHABLE_KEY_PLACEHOLDER">
  </script>

  <script>
    var subscriptionId = document.querySelector('#pay-button').dataset.subscriptionId;

    cryptopay.Button({
      createSubscription: function(actions) {
        return actions.subscription.fetch(subscriptionId);
      },
      onApprove: function(data, actions) {
        // Optional: add logic such as browser redirection or check data object content
      },
      defaultLang: 'en-US' // Optional: default language for payment page
    }).render("#pay-button")
  </script>

  <div id="pay-button" data-subscription-id="SUBSCRIPTION_UNIQUE_ID"></div>
</body>

Add a container element on your page and render the Crypto.com Pay button in it. Also pass the Subscription ID created in Step 5 into this container (attribute is data-subscription-id).

Then implement the createSubscription function. This function will be invoked when the customer clicks on the Crypto.com Pay button. Since you already have a Subscription ID from Step 3, you just have to provide it and the SDK will not create another new payment.

Then implement the onApprove function. You should add logic here to show the success message. Once Crypto.com Pay got your customer's payment authorization on the subscription, the onApprove function will be called.

Step 7: Verify subscription status

Retrieve the subscription

curl https://pay.crypto.com/api/subscriptions/SUBSCRIPTION_UNIQUE_ID \
  -u YOUR_SECRET_KEY_PLACEHOLDER:

On server side of your return_url page, retrieve the subscription and check whether the subscription status is active. See all the statuses here.

Step 8: Monitor events

After the subscription turned into active, it will collect payment for the first billing period right away. Invoice objects and its associated payment objects will be created automatically for each billing period. Cryptocurrency payment will be collect from customer's Crypto.com App automatically based on the currency setting they used when they approved the subscription.

You should monitor invoice.paid and invoice.payment_attempt_failed events for your subscriptions. Please refer to Webhooks for more details.

Subscription - Page Redirection

If you prefer a solution that has minimal impact to your user interface design, you may use your existing checkout interface, and redirect to Crypto.com subscription payment page when customers submit your checkout form. Once the subscription approval is made, the subscription payment page will redirect back to your store to finish your order flow.

Step 1: Register Crypto.com Pay Developer Access

Sign up for a Crypto.com Pay account, if you don't already have one.

Once you have access to the Crypto.com Pay Merchant Dashboard, You will be able to generate a secret key and publishable key pair. You should use the publishable key in the Crypto.com Pay SDK and the secret key when you directly interact with the Crypto.com Pay API.

Step 2: Create a Product and Pricing Plan

Create product and pricing plan

curl https://pay.crypto.com/api/products \
  -u YOUR_SECRET_KEY_PLACEHOLDER: \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter monthly subscription",
    "active": true,
    "description": "Newsletter monthly subscription",
    "metadata": {
      "ref_id": "6936acde-1697-456d-95c1-0afcce047b29"
    },
    "pricing_plans": [
      {
        "amount": 1000,
        "currency": "USD",
        "active": true,
        "description": "Newsletter monthly subscription pricing",
        "interval": "month",
        "interval_count": 1,
        "metadata": {
            "ref_id": "99213a90807b"
        },
        "purchase_type": "recurring"
      }
    ]
}'

On server side, obtain a pricing plan ID by creating a product and its pricing plan. Replace the YOUR_SECRET_KEY_PLACEHOLDER with your Secret Key. See Create a Product section for the schema of product and pricing plan objects that you should pass in.

You can also use the pricing plan ID of a pricing plan you created previously.

Response

{
  "id": "89630fd4-e900-40c9-a072-758f16d9dbdd",
  "account_id": "a5b1e789-fc2b-478b-a0be-3fbbc2607563",
  "active": true,
  "description": "Newsletter monthly subscription",
  "name": "Newsletter monthly subscription",
  "metadata": {
    "ref_id": "6936acde-1697-456d-95c1-0afcce047b29"
  },
  "created_at": 1628000625,
  "updated_at": 1628000625,
  "pricing_plans": [
    {
      "id": "2506cad4-fed6-49c0-98f5-34b0bedd6891",
      "active": true,
      "amount": 1000,
      "currency": "USD",
      "interval": "month",
      "interval_count": 1,
      "purchase_type": "recurring",
      "description": "Newsletter monthly subscription pricing",
      "metadata": {
          "ref_id": "99213a90807b"
      },
      "created_at": 1628000625,
      "updated_at": 1628000625,
    }
  ]
}

Step 3: Create a Customer

Create customer

curl https://pay.crypto.com/api/customers \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ: \
  -H "Content-Type: application/json" \
  -d '{
    "ref_id": "6ded84e75449",
    "name": "John Doe"
  }'

Similarly, on server side, obtain a customer ID by creating a customer. See Create a Customer section for the schema of customer object that you should pass in.

You can also use the customer ID of a customer you created previously.

Response

{
  "id": "8e384561-d781-4868-9b66-3fb2d7a83ba5",
  "email": null,
  "ref_id": "6ded84e75449",
  "name": "John Doe",
  "created_at": 1627917897,
  "updated_at": 1627917897
}

Step 4: Create a Subscription

Create subscription

curl https://pay.crypto.com/api/subscriptions \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ: \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "8e384561-d781-4868-9b66-3fb2d7a83ba5",
    "return_url": "http://YOUR_WEBSITE.com/orders/123/complete",
    "billing_cycle_anchor": 1625943925,
    "interval": "month",
    "metadata": {
      "ref_id": "34196851011b"
    },
    "items": [
      {
        "plan_id": "2506cad4-fed6-49c0-98f5-34b0bedd6891",
        "quantity": 1
      }
    ]
  }'

With customer ID and pricing plan ID, now you can create a subscription object. You also need to provide a billing_cycle_anchor which is the starting time of your billing cycle. See Create a Subscription section for the schema of subscription object that you should pass in.

It is a must for this flow to provide return_url when creating subscription. The subscription returned will contain a subscription_url for the next step.

Response

{
  "id": "SUBSCRIPTION_UNIQUE_ID",
  "created_at": 1625943925,
  "currency": "USD",
  "amount": 1000,
  "current_period_end": 1628622325,
  "current_period_start": 1625943925,
  "auto_end_at": null,
  "ended_at": null,
  "cancelled_at": null,
  "interval": "month",
  "interval_count": 1,
  "live_mode": true,
  "metadata": {
    "ref_id": "34196851011b"
  },
  "note": null,
  "recipient": "Crypto.com Shop",
  "reference": null,
  "return_url": "http://YOUR_WEBSITE.com/orders/123/complete",
  "subscription_url": "https://js.crypto.com/subscription?publishableKey=XXXsdkMeta=YYY",
  "status": "pending",
  "updated_at": 1625943925
}

Step 5: Redirect to payment page

After creating the subscription object, you will need to redirect customers to subscription_url to finish the payment authorization. After the payment is authorized, the subscription will become active. The payment page will then redirect customers back to return_url (or cancel_url if there is any issue).

Step 6: Verify subscription status

Retrieve the subscription

curl https://pay.crypto.com/api/subscriptions/SUBSCRIPTION_UNIQUE_ID \
  -u YOUR_SECRET_KEY_PLACEHOLDER:

On server side of your return_url page, retrieve the subscription and check whether the subscription status is active. See all the statuses here.

Step 7: Monitor events

After the subscription turned into active, it will collect payment for the first billing period right away. Invoice objects and its associated payment objects will be created automatically for each billing period. Cryptocurrency payment will be collect from customer's Crypto.com App automatically based on the currency setting they used when they approved the subscription.

You should monitor invoice.paid and invoice.payment_attempt_failed events for your subscriptions. Please refer to Webhooks for more details.

Promotion Banner SDK

The Crypto.com Pay promotion banners are an effective way to let customers be aware of the Crypto.com Pay payment option. These banners are often presented at the upstream of the shopping journey (e.g. shop home page, the product details pages).

If you are eligible for the Pay Rewards program, you can use the banners to drive more sales by letting your customers know that they can pay with crypto to earn rebates.

When your customers clicked the banners, there will be a popup with high-level checkout steps to guide them to pay using Crypto.com Pay.

(Theme: Black Font on Grey (default))

(Theme: White Font on Grey)

Add to Your Website

Step 1: Register Crypto.com Pay Developer Access

Sign up for a Crypto.com Pay account. You can skip this step if you already have one account. Once you have access to the Crypto.com Pay Merchant Dashboard, you will be able to generate a secret key and publishable key pair. You should use the publishable key in the Crypto.com Pay SDK and the secret key when you directly interact with the Crypto.com Pay API.

Step 2: Add the Crypto.com Pay SDK Script

Add the script

<body>
  <script src="https://js.crypto.com/sdk?publishable-key=YOUR_PUBLISHABLE_KEY_PLACEHOLDER"></script>
</body>

Add the following script to your web page. Replace the YOUR_PUBLISHABLE_KEY_PLACEHOLDER with your Publishable Key.

Step 3: Render the Crypto.com Pay Promotion Banner

Add a container element

<div class="crypto-pay-banner"></div>

Add a container element on your page and render the Crypto.com Pay promotion banner in it. If you want to add multiple Crypto.com promotion banners on the same page, then add multiple container elements on your page and render them.

Implement the createBanner function

<body>
 <script src="https://js.crypto.com/sdk?publishable-key=YOUR_PUBLISHABLE_KEY_PLACEHOLDER">
 </script>
 <script>
  cryptopay.BannerHelper.createBanner({
      theme: 'black-font-on-grey',
      size: 'medium',
      font: 'sf pro text',
      bannerMessage: 'earn-rebate',
      targetNodes: '.crypto-pay-banner'
    })
 </script>
</body>

Then implement the createBanner function. The promotion banner will be shown on your page after the function is invoked.

Refer to promotion banner properties to see the possible values that you can set. The properties have default values. If no value or an invalid value is passed, the default value is used.

Promotion Banner Properties

Add to Your Shopify Shop

If you are using Shopify, please refer to the Shopify Setup Guide for the instructions to add the promotion banner in your connected Shopify Shop.

Mobile Integration

You can follow the page redirection guide above to integrate Crypto.com Pay in your mobile App.

Instead of redirecting from your website to the payment page, you will need to open a WebView in your App to display the payment page. Once payment becomes succeeded, it will redirect to the page you specified, and therefore you can capture the redirection event and handle order completion.

You may contact [email protected] to get code examples for mobile integrations.

eCommerce Solution Plugins

Crypto.com Pay offers plugins with many of the world’s popular eCommerce solutions and the list keeps growing.

Please find below for the setup guide of the plugins so you can get a quick start.

List of Plugins:

Shopify

WooCommerce

Prestashop

Magento 2

Ecwid

OpenCart

nopCommerce

If you have any suggestions to our plugins, please feel free to contact us at [email protected].

Invoice

You can also use the Merchant Dashboard to send invoice emails to your customers. No integration is necessary. Please refer to this FAQ article for more information.

API for individual invoice creation will be available soon.

API Reference

Base URL

https://pay.crypto.com/api

The Crypto.com Pay API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the Crypto.com Pay API in test mode, which does not affect your live data or interact with the payment networks. The API key you use to authenticate the request determines whether the request is live mode or test mode.

The Crypto.com Pay API is still under heavy development and there might be breaking changes. Merchant will be notified in advance if there such change is necessary.

Authentication

Authenticated Request

curl https://pay.crypto.com/api/payments \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ:
# The colon prevents curl from asking for a password.

The Crypto.com Pay API uses API keys to authenticate requests. You can view and manage your API keys in the Merchant Dashboard. You should be using your Secret Key.

Test mode secret keys have the prefix sk_test_ and live mode secret keys have the prefix sk_live_.

Your Secret Key carries many privileges, so be sure to keep them secure! Do not share them in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your Secret Key as the basic auth username value. You do not need to provide a password.

If you need to authenticate via bearer auth (e.g., for a cross-origin request), use -H "Authorization: Bearer sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ" instead of -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Errors

The error object

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "param": "id"
  }
}

Crypto.com Pay API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a payment failed, etc.). Codes in the 5xx range indicate an error with Crypto.com Pay's servers.

Attributes

Resources

Payments

Endpoints

POST /api/payments
GET /api/payments/:id
POST /api/payments/:id/cancel
GET /api/payments

To accept a crypto payment, you need to create a Payment object. You can retrieve individual payments as well as list all payments. Payments are identified by their unique ID.

The Payment Object

The Payment Object

{
  "id": "fa176d2e-8f58-419d-a531-e2c8e4dc3fa9",
  "amount": 2500,
  "amount_refunded": 0,
  "created": 1555098161,
  "crypto_currency": "CRO",
  "crypto_amount": "1894.8",
  "currency": "USD",
  "customer_id": null,
  "payment_url": "https://js.crypto.com/sdk/payments/checkout/set_wallet?publishableKey=XXX&sdkMeta=YYY",
  "return_url": "http://YOUR_WEBSITE.com/orders/123/complete",
  "cancel_url": "http://YOUR_WEBSITE.com/orders/123/fail",
  "description": "Crypto.com Tee (Unisex)",
  "live_mode": false,
  "metadata": {
    "customer_name": "John Doe"
  },
  "order_id": "640cf83d-a316-4030-9878-71be1d98b737",
  "recipient": "Crypto.com Shop",
  "refunded": false,
  "status": "pending",
  "expired_at": 1555098461
}

Attributes

Pricing Currencies

Supported Pricing Currencies (Fiat)

Supported Pricing Currencies (Crypto)

Create a Payment

POST /payments

curl https://pay.crypto.com/api/payments \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ: \
  -d amount=2500 \
  -d currency=USD \
  -d description="Crypto.com Tee (Unisex)"

To accept a crypto payment, you need to create a Payment object. If your API keys is in test mode, no crypto is actually accepted, although everything else will occur as if in live mode. (Crypto.com Pay assumes that the payment would have completed successfully in test mode).

Response

{
  "id": "fa176d2e-8f58-419d-a531-e2c8e4dc3fa9",
  "amount": 2500,
  "amount_refunded": 0,
  "created": 1555098161,
  "crypto_currency": "CRO",
  "crypto_amount": "1894.8",
  "currency": "USD",
  "payment_url": "https://js.crypto.com/sdk/payments/checkout/set_wallet?publishableKey=XXX&sdkMeta=YYY",
  "return_url": "http://YOUR_WEBSITE.com/orders/123/complete",
  "cancel_url": "http://YOUR_WEBSITE.com/orders/123/fail",
  "description": "Crypto.com Tee (Unisex)",
  "live_mode": false,
  "metadata": {
    "customer_name": "John Doe"
  },
  "order_id": "640cf83d-a316-4030-9878-71be1d98b737",
  "recipient": "Crypto.com Shop",
  "refunded": false,
  "status": "pending",
  "onchain_allowed": true,
  "expired_at": 1555098261
}

Arguments

Returns

Returns the payment object if the creation succeeded. This call will return an error if something goes wrong.

Get Payment by ID

GET /payments/:id

curl https://pay.crypto.com/api/payments/fa176d2e-8f58-419d-a531-e2c8e4dc3fa9 \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ:

Retrieves the details of a payment that has previously been created. Supply the unique payment ID that was returned from your previous request, and the API will return the corresponding payment information.

Response

{
  "id": "fa176d2e-8f58-419d-a531-e2c8e4dc3fa9",
  "amount": 2500,
  "amount_refunded": 0,
  "created": 1555098161,
  "crypto_currency": "CRO",
  "crypto_amount": "1894.8",
  "currency": "USD",
  "customer_id": null,
  "payment_url": "https://js.crypto.com/sdk/payments/checkout/set_wallet?publishableKey=XXX&sdkMeta=YYY",
  "return_url": "http://YOUR_WEBSITE.com/orders/123/complete",
  "cancel_url": "http://YOUR_WEBSITE.com/orders/123/fail",
  "description": "Crypto.com Tee (Unisex)",
  "live_mode": false,
  "metadata": {
    "customer_name": "John Doe"
  },
  "order_id": "640cf83d-a316-4030-9878-71be1d98b737",
  "recipient": "Crypto.com Shop",
  "refunded": false,
  "status": "succeeded",
  "expired_at": 1555098461
}

Arguments

Returns

Returns a payment if a valid identifier was provided, and returns an error otherwise.

Cancel a Payment

POST /payments/:id/cancel

curl https://pay.crypto.com/api/payments/fa176d2e-8f58-419d-a531-e2c8e4dc3fa9/cancel \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ:

Cancelling a payment indicates that you do not want the payment to go through anymore. The status of payment will change from pending to cancelled. Cancelling a payment is irreversible. Approved payments can't be cancelled.

Response

{
  "id": "fa176d2e-8f58-419d-a531-e2c8e4dc3fa9",
  "amount": 2500,
  "amount_refunded": 0,
  "created": 1555098161,
  "crypto_currency": "CRO",
  "crypto_amount": "1894.8",
  "currency": "USD",
  "customer_id": null,
  "payment_url": "https://js.crypto.com/sdk/payments/checkout/set_wallet?publishableKey=XXX&sdkMeta=YYY",
  "return_url": "http://YOUR_WEBSITE.com/orders/123/complete",
  "cancel_url": "http://YOUR_WEBSITE.com/orders/123/fail",
  "description": "Crypto.com Tee (Unisex)",
  "live_mode": false,
  "metadata": {
    "customer_name": "John Doe"
  },
  "order_id": "640cf83d-a316-4030-9878-71be1d98b737",
  "recipient": "Crypto.com Shop",
  "refunded": false,
  "status": "cancelled",
  "expired_at": 1555098461
}

Arguments

Returns

Returns the payment object.

List all Payments

GET /payments

curl https://pay.crypto.com/api/payments?page=1&captured_at_begin=1609430400&per_page=10 \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ:

Returns a list of payments you’ve previously created. The payments are returned in sorted order, with the most recent payment appearing first.

You can optionally provide parameters to filter out the results.

Response

{
  "items": [
    {
      "id": "fa176d2e-8f58-419d-a531-e2c8e4dc3fa9",
      "amount": 2500,
      "amount_refunded": 0,
      "created": 1555098161,
      "crypto_currency": "CRO",
      "crypto_amount": "1894.8",
      "currency": "USD",
      "customer_id": null,
      "payment_url": "https://js.crypto.com/sdk/payments/checkout/set_wallet?publishableKey=XXX&sdkMeta=YYY",
      "return_url": "http://YOUR_WEBSITE.com/orders/123/complete",
      "cancel_url": "http://YOUR_WEBSITE.com/orders/123/fail",
      "description": "Crypto.com Tee (Unisex)",
      "live_mode": false,
      "metadata": {
        "customer_name": "John Doe"
      },
      "order_id": "640cf83d-a316-4030-9878-71be1d98b737",
      "recipient": "Crypto.com Shop",
      "refunded": false,
      "status": "cancelled",
      "expired_at": 1555098461
    }
  ],
  "meta": {
    "current_page": 1,
    "current_size": 1,
    "next_page": null,
    "per_page": 10,
    "total_pages": 1
  }
}

Arguments

Returns

Array of payment objects with paging meta information.

Refunds

Endpoints

POST /api/refunds
GET /api/refunds/:id
GET /payments/:payment_id/refunds

Refund objects allow you to refund a payment that has previously been created but not yet refunded. Funds will be paid from the merchant account balance.

The Refund Object

The Refund Object

{
  "id": "53c6ac55-2008-487f-a1c7-65b120b4e922",
  "payment_id": "1d065c74-1162-41b2-baf0-de90742e9f28",
  "currency": "USD",
  "amount": 2500,
  "debit_currency": "TUSD",
  "debit_amount": 2500,
  "reason": "requested_by_customer",
  "description": "Refund for Order#32",
  "created": 1555098162,
  "status": "succeeded",
  "live_mode": true,
  "onchain_email_last_sent_at": null,
  "onchain_wallet_provided_at": 1623915196,
  "transferred_at": 1623915205,
  "refund_currency": "CRO",
  "refund_amount": "121.09117681",
  "refund_destination": "Crypto.com Wallet App"
}

Attributes

Request a Refund

POST /refunds

curl https://pay.crypto.com/api/refunds \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ: \
  -d payment_id="8ddee625-d175-4c55-a5e0-5ed8c68e3cd1" \
  -d amount=100 \
  -d reason="requested_by_customer" \
  -d description="Refund for Order#33" \

Request a refund for a specific payment you made before. Refund can be partial as long as the total requested refund amount does not exceed the original payment amount.

Response

{
  "id": "4639e9bb-f85c-4f62-9d52-56dc0a8eb51b",
  "status": "pending",
  "payment_id": "8ddee625-d175-4c55-a5e0-5ed8c68e3cd1",
  "currency": "USD",
  "amount": 100,
  "reason": "requested_by_customer",
  "description": "Refund for Order#33",
  "created": 1555098162
}

Arguments

Returns

Returns refund object if the refund action succeeded. This call will return an error if something goes wrong. A common error is "refund exceeds payment limit" when the total requested refund amount exceeded the original payment amount.

Get Refund by Refund ID

GET /refunds/:id

curl https://pay.crypto.com/api/refunds/53c6ac55-2008-487f-a1c7-65b120b4e922 \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ:

Retrieves the details of a refund that has previously been requested. Supply the unique refund ID that was returned from your previous request, and the API will return the corresponding refund information.

Response

{
  "id": "53c6ac55-2008-487f-a1c7-65b120b4e922",
  "payment_id": "1d065c74-1162-41b2-baf0-de90742e9f28",
  "currency": "USD",
  "amount": 2500,
  "debit_currency": "TUSD",
  "debit_amount": 2500,
  "reason": "requested_by_customer",
  "description": "Refund for Order#32",
  "created": 1555098162,
  "status": "succeeded",
  "live_mode": true,
  "onchain_email_last_sent_at": null,
  "onchain_wallet_provided_at": 1623915196,
  "transferred_at": 1623915205,
  "refund_currency": "CRO",
  "refund_amount": "121.09117681",
  "refund_destination": "Crypto.com Wallet App"
}

Arguments

Returns

Returns a refund if a valid identifier was provided, and returns an error otherwise.

Get Refunds by Payment ID

GET /payments/:payment_id/refunds

curl https://pay.crypto.com/api/payments/1d065c74-1162-41b2-baf0-de90742e9f28/refunds \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ:

Retrieves the list of refunds that is related to a payment. Supply the unique payment ID, and the API will return the corresponding list of refund information.

Response

[
  {
    "id": "53c6ac55-2008-487f-a1c7-65b120b4e922",
    "currency": "USD",
    "amount": 2500,
    "debit_currency": "TUSD",
    "debit_amount": 2500,
    "created": 1623915196,
    "reason": "Requested by customer",
    "description": "test",
    "payment_id": "1d065c74-1162-41b2-baf0-de90742e9f28",
    "status": "succeeded",
    "live_mode": true,
    "onchain_email_last_sent_at": null,
    "onchain_wallet_provided_at": 1623915196,
    "transferred_at": 1623915205,
    "refund_currency": "CRO",
    "refund_amount": "121.09117681",
    "refund_destination": "Crypto.com Wallet App"
  }
]

Arguments

Returns

Returns a list refunds of the payment if a valid identifier was provided, and returns an error otherwise.

Rebounds

Endpoints

GET /payments/:payment_id/rebounds

Rebound objects allow you to check the rebound details of a payment, if it has been rebounded.

The Rebound Object

The Rebound Object

{
  "id": "5b0f62f2-0ab4-4d2f-900a-0cb33ea08bc6",
  "payment_id": "c15e723b-c3dc-43d4-a587-e6c3aa527578",
  "created_at": 1624012898,
  "onchain_email_created_at": null,
  "onchain_wallet_provided_at": 1624012898,
  "transferred_at": null,
  "crypto_currency": "ETH",
  "crypto_amount": "0.941",
  "destination": "External Wallets",
  "reason": "overpaid",
  "status": "withdraw_requested"
}

Attributes

Get Rebounds by Payment ID

GET /payments/:payment_id/rebounds

curl https://pay.crypto.com/api/payments/c15e723b-c3dc-43d4-a587-e6c3aa527578/rebounds \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ:

Retrieves the list of rebounds that is related to a payment. Supply the unique payment ID, and the API will return the corresponding list of rebound information.

Response

[
  {
    "id": "5b0f62f2-0ab4-4d2f-900a-0cb33ea08bc6",
    "payment_id": "c15e723b-c3dc-43d4-a587-e6c3aa527578",
    "created_at": 1624012898,
    "onchain_email_created_at": null,
    "onchain_wallet_provided_at": 1624012898,
    "transferred_at": null,
    "crypto_currency": "ETH",
    "crypto_amount": "0.941",
    "destination": "External Wallet",
    "reason": "overpaid",
    "status": "withdraw_requested"
  }
]

Arguments

Returns

Returns a list rebounds of the payment if a valid identifier was provided, and returns an error otherwise.

Customers

Endpoints

POST /api/customers
GET /api/customers/:id
PATCH /api/customers/:id
GET /api/customers

Customer object is necessary for identifying the customer when creating a subscription. With the API, you can retrieve one single customer as well as list all customers. Customers are identified by their unique ID.

The Customer Object

The Customer Object

{
  "id": "8e384561-d781-4868-9b66-3fb2d7a83ba5",
  "email": null,
  "ref_id": "6ded84e75449",
  "name": "John Doe",
  "created_at": 1627917897,
  "updated_at": 1627917897
}

Attributes

Create a Customer

POST /customers

curl https://pay.crypto.com/api/customers \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ: \
  -H "Content-Type: application/json" \
  -d '{
    "ref_id": "6ded84e75449",
    "name": "John Doe"
  }'

Create a customer object for subscription.

Attributes

Returns

Returns the customer object if succeeded. This call will return an error if something goes wrong.

Get Customer by ID

GET /customers/:id

curl https://pay.crypto.com/api/customers/8e384561-d781-4868-9b66-3fb2d7a83ba5 \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ:

Retrieves the details of a customer by the unique customer ID, which was returned from your creation request.

Response

{
  "id": "8e384561-d781-4868-9b66-3fb2d7a83ba5",
  "email": null,
  "ref_id": "6ded84e75449",
  "name": "John Doe",
  "created_at": 1627917897,
  "updated_at": 1627917897
}

Arguments

Returns

Returns a refund if a valid identifier was provided, and returns an error otherwise.

Update a Customer

PATCH /customers/:id

curl https://pay.crypto.com/api/customers/8e384561-d781-4868-9b66-3fb2d7a83ba5 \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ: \
  -H "Content-Type: application/json" \
  -X PATCH \
  -d '{
    "email": "[email protected]"
  }'

Update the details of a customer.

Response

{
  "id": "8e384561-d781-4868-9b66-3fb2d7a83ba5",
  "email": "[email protected]",
  "ref_id": "6ded84e75449",
  "name": "John Doe",
  "created_at": 1627917897,
  "updated_at": 1627973748
}

Returns

Returns the updated customer object if succeeded. This call will return an error if something goes wrong.

List all Customers

GET /customers

curl https://pay.crypto.com/api/customers?page=1&per_page=10 \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ:

Returns a list of customers you’ve previously created.

Response

{
  "items": [
    {
      "id": "8e384561-d781-4868-9b66-3fb2d7a83ba5",
      "email": "[email protected]",
      "ref_from": null,
      "ref_id": "6ded84e75449",
      "name": "John Doe",
      "created_at": 1627917897,
      "updated_at": 1627984495
    }
  ],
  "meta": {
    "current_page": 1,
    "current_size": 1,
    "next_page": null,
    "per_page": 10,
    "total_pages": 1
  }
}

Arguments

Returns

Array of customer objects with paging meta information.

Products

Endpoints

POST /api/products
GET /api/products/:id
GET /api/products

Product object is necessary for identifying the product and pricing when creating a subscription. With the API, you can retrieve one single product as well as list all products. products are identified by their unique ID.

The Product Object

The Product Object

{
  "id": "89630fd4-e900-40c9-a072-758f16d9dbdd",
  "account_id": "a5b1e789-fc2b-478b-a0be-3fbbc2607563",
  "active": true,
  "description": "Newsletter monthly subscription",
  "name": "Newsletter monthly subscription",
  "metadata": {
    "ref_id": "6936acde-1697-456d-95c1-0afcce047b29"
  },
  "created_at": 1628000625,
  "updated_at": 1628000625,
  "pricing_plans": [
    {
      "id": "2506cad4-fed6-49c0-98f5-34b0bedd6891",
      "active": true,
      "amount": 1000,
      "currency": "USD",
      "interval": "month",
      "interval_count": 1,
      "purchase_type": "recurring",
      "description": "Newsletter monthly subscription pricing",
      "metadata": {
          "ref_id": "99213a90807b"
      },
      "created_at": 1628000625,
      "updated_at": 1628000625,
    }
  ]
}

Attributes - Product

Attributes - Pricing Plan

Create a Product

POST /products

curl https://pay.crypto.com/api/products \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ: \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter monthly subscription",
    "active": true,
    "description": "Newsletter monthly subscription",
    "metadata": {
      "ref_id": "6936acde-1697-456d-95c1-0afcce047b29"
    },
    "pricing_plans": [
      {
        "amount": 1000,
        "currency": "USD",
        "active": true,
        "description": "Newsletter monthly subscription pricing",
        "interval": "month",
        "interval_count": 1,
        "metadata": {
            "ref_id": "99213a90807b"
        },
        "purchase_type": "recurring"
      }
    ]
}'

Create a product object for subscription.

Attributes - Product

Attributes - Pricing Plan

Returns

Returns the product object if succeeded. This call will return an error if something goes wrong.

Get Product by ID

GET /products/:id

curl https://pay.crypto.com/api/products/89630fd4-e900-40c9-a072-758f16d9dbdd \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ:

Retrieves the details of a product by the unique product ID, which was returned from your creation request.

Response

{
  "id": "89630fd4-e900-40c9-a072-758f16d9dbdd",
  "account_id": "a5b1e789-fc2b-478b-a0be-3fbbc2607563",
  "active": true,
  "description": "Newsletter monthly subscription",
  "name": "Newsletter monthly subscription",
  "metadata": {
    "ref_id": "6936acde-1697-456d-95c1-0afcce047b29"
  },
  "created_at": 1628000625,
  "updated_at": 1628000625,
  "pricing_plans": [
    {
      "id": "2506cad4-fed6-49c0-98f5-34b0bedd6891",
      "active": true,
      "amount": 1000,
      "currency": "USD",
      "interval": "month",
      "interval_count": 1,
      "purchase_type": "recurring",
      "description": "Newsletter monthly subscription pricing",
      "metadata": {
          "ref_id": "99213a90807b"
      },
      "created_at": 1628000625,
      "updated_at": 1628000625,
    }
  ]
}

Arguments

Returns

Returns a refund if a valid identifier was provided, and returns an error otherwise.

List all Products

GET /products

curl https://pay.crypto.com/api/products?page=1&per_page=10 \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ:

Returns a list of products you’ve previously created.

Response

{
  "items": [
    {
      "id": "89630fd4-e900-40c9-a072-758f16d9dbdd",
      "account_id": "a5b1e789-fc2b-478b-a0be-3fbbc2607563",
      "active": true,
      "description": "Newsletter monthly subscription",
      "name": "Newsletter monthly subscription",
      "metadata": {
        "ref_id": "6936acde-1697-456d-95c1-0afcce047b29"
      },
      "created_at": 1628000625,
      "updated_at": 1628000625
    }
  ],
  "meta": {
    "current_page": 1,
    "current_size": 1,
    "next_page": null,
    "per_page": 10,
    "total_pages": 1
  }
}

Arguments

Returns

Array of product objects with paging meta information.

Subscriptions

Endpoints

POST /api/subscriptions
GET /api/subscriptions/:id
POST /api/subscriptions/:id/cancel
GET /api/subscriptions

To accept subscription payments from customers, you can create subscriptions using this API. You can retrieve individual subscription as well as list all subscriptions. Subscriptions are identified by their unique ID.

The Subscription Object

The Subscription Object

{
  "id": "fc3398b4-710c-48df-bfe1-a4b27530c19f",
  "created_at": 1625943925,
  "currency": "USD",
  "amount": 1000,
  "current_period_end": 1628622325,
  "current_period_start": 1625943925,
  "auto_end_at": null,
  "ended_at": null,
  "cancelled_at": null,
  "interval": "month",
  "interval_count": 1,
  "live_mode": true,
  "metadata": {
    "ref_id": "34196851011b"
  },
  "note": null,
  "recipient": "Crypto.com Shop",
  "reference": null,
  "return_url": "http://YOUR_WEBSITE.com/orders/123/complete",
  "subscription_url": "https://js.crypto.com/subscription?publishableKey=XXXsdkMeta=YYY",
  "status": "pending",
  "updated_at": 1625943925
}

Attributes

Create a Subscription

POST /subscriptions

curl https://pay.crypto.com/api/subscriptions \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ: \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "8e384561-d781-4868-9b66-3fb2d7a83ba5",
    "billing_cycle_anchor": 1625943925,
    "metadata": {
      "ref_id": "34196851011b"
    },
    "items": [
      {
        "plan_id": "2506cad4-fed6-49c0-98f5-34b0bedd6891",
        "quantity": 1
      }
    ]
  }'

Create a subscription object to automatically collect subscription payments from customers.

Arguments

Returns

Returns the subscription object if the creation succeeded. This call will return an error if something goes wrong.

Get Subscription by ID

GET /subscriptions/:id

curl https://pay.crypto.com/api/subscriptions/fc3398b4-710c-48df-bfe1-a4b27530c19f \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ:

Retrieves the details of a subscription by the unique subscription ID, which was returned from your creation request.

Response

{
  "id": "fc3398b4-710c-48df-bfe1-a4b27530c19f",
  "created_at": 1625943925,
  "currency": "USD",
  "amount": 1000,
  "current_period_end": 1628622325,
  "current_period_start": 1625943925,
  "auto_end_at": null,
  "ended_at": null,
  "cancelled_at": null,
  "interval": "month",
  "interval_count": 1,
  "live_mode": true,
  "metadata": {
    "ref_id": "34196851011b"
  },
  "note": null,
  "recipient": "Crypto.com Shop",
  "reference": null,
  "return_url": "http://YOUR_WEBSITE.com/orders/123/complete",
  "subscription_url": "https://js.crypto.com/subscription?publishableKey=XXXsdkMeta=YYY",
  "status": "pending",
  "updated_at": 1625943925
}

Arguments

Returns

Returns a subscription if a valid identifier was provided, and returns an error otherwise.

Cancel a Subscription

POST /subscriptions/:id/cancel

curl https://pay.crypto.com/api/subscriptions/fc3398b4-710c-48df-bfe1-a4b27530c19f/cancel \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ:

Cancels an active subscription so that Crypto.com Pay will no longer collect payments automatically for this subscription.

Response

{
  "id": "fc3398b4-710c-48df-bfe1-a4b27530c19f",
  "created_at": 1625943925,
  "currency": "USD",
  "amount": 1000,
  "current_period_end": 1628622325,
  "current_period_start": 1625943925,
  "auto_end_at": null,
  "ended_at": null,
  "cancelled_at": null,
  "interval": "month",
  "interval_count": 1,
  "live_mode": true,
  "metadata": {
    "ref_id": "34196851011b"
  },
  "note": null,
  "recipient": "Crypto.com Shop",
  "reference": null,
  "return_url": "http://YOUR_WEBSITE.com/orders/123/complete",
  "subscription_url": "https://js.crypto.com/subscription?publishableKey=XXXsdkMeta=YYY",
  "status": "cancelled",
  "updated_at": 1625943925
}

Arguments

Returns

Returns the subscription object.

List all Subscriptions

GET /subscriptions

curl https://pay.crypto.com/api/subscriptions?page=1&captured_at_begin=1609430400&per_page=10 \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ:

Returns a list of subscriptions you’ve previously created.

Response

{
  "items": [
    {
      "id": "fc3398b4-710c-48df-bfe1-a4b27530c19f",
      "created_at": 1625943925,
      "currency": "USD",
      "amount": 1000,
      "current_period_end": 1628622325,
      "current_period_start": 1625943925,
      "auto_end_at": null,
      "ended_at": null,
      "cancelled_at": null,
      "interval": "month",
      "interval_count": 1,
      "live_mode": true,
      "metadata": {
        "ref_id": "34196851011b"
      },
      "note": null,
      "recipient": "Crypto.com Shop",
      "reference": null,
      "return_url": "http://YOUR_WEBSITE.com/orders/123/complete",
      "subscription_url": "https://js.crypto.com/subscription?publishableKey=XXXsdkMeta=YYY",
      "status": "pending",
      "updated_at": 1625943925
    }
  ],
  "meta": {
    "current_page": 1,
    "current_size": 1,
    "next_page": null,
    "per_page": 10,
    "total_pages": 1
  }
}

Arguments

Returns

Array of subscription objects with paging meta information.

Invoices

Invoice objects will be created when there are new invoices created in Merchant Dashboard, or by recurring invoices and subscriptions.

The Invoice Object

The Invoice Object

{
  "id": "ace5a4fb-59a5-4231-85e9-356720bd1172",
  "status": "failed",
  "amount_fractional": 1000,
  "currency": "USD",
  "customer": {
      "id": "17c9c267-ea9a-4613-bb80-08d4a91b692f",
      "email": null
  },
  "note": "subscription create",
  "subscription_id": "fe4aa90a-7961-4a32-8ed7-f96c1cda2854"
}

Attributes

Sub-merchants

Endpoints

POST /sub_merchants
GET /sub_merchants/:id
GET /sub_merchants

Acquirers can manage their sub-merchants efficiently with our APIs, with which you can create sub-merchants, and retrieve information of all your sub-merchants without doing it on the Merchant Dashboard manually. Sub-merchants are identified by their unique ID and the sub-merchant ID is required for Acquirers when creating payments or refunds.

The Sub-merchant Object

The Sub-merchant Object

{
  "id": "e884e700-e3c7-47e3-85c4-3baf114ddacd",
  "external_id": "Sub merchant123",
  "name": "Sub merchant 123",
  "business_settings": {
    "website": "https://example.com",
    "legal_entity_name": "Sub merchant One Two Three",
    "country": "US",
    "business_category": "corporation",
    "business_industry": "5691",
    "registration_number": "123456",
    "business_address": "Unit A, 12/F, Street ABC",
    "business_address2": "Building XYZ",
    "province": "Los Angeles",
    "region": "California",
    "zip_code": "90003",
    "service_region": "Global",
    "service_country": ""
  },
  "support_email": "[email protected]",
  "active": true,
  "cashback_rate": "0.01",
  "created_at": 1657090466,
  "updated_at": 1657090466,
  "avatar": "https://pay.crypto.com/rails/active_storage/blobs/easdJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaEpJaWsxWTJWbU9XWmhNQUxUUmlNVEV0T0RFeE9DMWxZak0yTUdGbFpUTTNNVFVHT2daRlZBPInB1ciI6ImJsb2JfaWQifX0=--fd31711455894547f085asdsad14ceb56af1f2f/logo_1.png",
  "live_account_enabled": true,
}

Attributes

Attributes - Business Settings

Create a Sub-merchant

POST /sub_merchants

curl https://pay.crypto.com/api/sub_merchants \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ: \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "Sub merchant123",
    "name": "Sub merchant 123",
    "support_email": "[email protected]",
    "business_settings": {
      "website": "https://example.com",
      "legal_entity_name": "Sub merchant One Two Three",
      "business_category": "corporation",
      "country": "US",
      "business_industry": "5691",
      "registration_number": "123456",
      "business_address": "Unit A, 12/F, Street ABC",
      "province": "Los Angeles",
      "region": "California",
      "zip_code": "90003"
    }
  }'

Create a sub-merchant object.

Attributes

Attributes - Business Settings

Returns

Returns the sub-merchant object if succeeded. This call will return an error if something goes wrong.

Get Sub-merchant by ID

GET /sub_merchants/:id

curl https://pay.crypto.com/api/sub_merchants/e884e700-e3c7-47e3-85c4-3baf114ddacd \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ:

Retrieves the details of a sub-merchant by the unique sub-merchant ID (NOT the external_id), which was returned from your creation request.

Response

{
  "id": "e884e700-e3c7-47e3-85c4-3baf114ddacd",
  "external_id": "Sub merchant123",
  "name": "Sub merchant 123",
  "business_settings": {
    "website": "https://example.com",
    "legal_entity_name": "Sub merchant One Two Three",
    "country": "US",
    "business_category": "corporation",
    "business_industry": "5691",
    "registration_number": "123456",
    "business_address": "Unit A, 12/F, Street ABC",
    "business_address2": "Building XYZ",
    "province": "Los Angeles",
    "region": "California",
    "zip_code": "90003",
    "service_region": "Global",
    "service_country": ""
  },
  "support_email": "[email protected]",
  "active": true,
  "cashback_rate": "0.01",
  "created_at": 1657090466,
  "updated_at": 1657090466,
  "avatar": "https://pay.crypto.com/rails/active_storage/blobs/easdJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaEpJaWsxWTJWbU9XWmhNQUxUUmlNVEV0T0RFeE9DMWxZak0yTUdGbFpUTTNNVFVHT2daRlZBPInB1ciI6ImJsb2JfaWQifX0=--fd31711455894547f085asdsad14ceb56af1f2f/logo_1.png",
  "live_account_enabled": true,
}

Arguments

Returns

Returns a sub-merchant object if a valid identifier was provided, and returns an error otherwise.

List all Sub-merchants

GET /sub_merchants

curl https://pay.crypto.com/api/sub_merchants?page=1&per_page=10 \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ:

Returns a list of sub-merchants you’ve previously created.

Response

{
  "items": [
    {
      "id": "e884e700-e3c7-47e3-85c4-3baf114ddacd",
      "external_id": "Sub merchant123",
      "name": "Sub merchant 123",
      "business_settings": {
        "website": "https://example.com",
        "legal_entity_name": "Sub merchant One Two Three",
        "country": "US",
        "business_category": "corporation",
        "business_industry": "5691",
        "registration_number": "123456",
        "business_address": "Unit A, 12/F, Street ABC",
        "business_address2": "Building XYZ",
        "province": "Los Angeles",
        "region": "California",
        "zip_code": "90003",
        "service_region": "Global",
        "service_country": ""
        },
      "support_email": "[email protected]",
      "active": true,
      "cashback_rate": "0.01",
      "created_at": 1657090466,
      "updated_at": 1657090466,
      "avatar": "https://pay.crypto.com/rails/active_storage/blobs/easdJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaEpJaWsxWTJWbU9XWmhNQUxUUmlNVEV0T0RFeE9DMWxZak0yTUdGbFpUTTNNVFVHT2daRlZBPInB1ciI6ImJsb2JfaWQifX0=--fd31711455894547f085asdsad14ceb56af1f2f/logo_1.png",
      "live_account_enabled": true,
    }
  ],
  "meta": {
    "current_page": 1,
    "current_size": 1,
    "next_page": null,
    "per_page": 10,
    "total_pages": 1
  }
}

Arguments

Returns

Array of sub-merchants objects with paging meta information.

Idempotency

curl https://pay.crypto.com/api/refunds \
  -u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ: \
  -H "Idempotency-Key: azVNQUJTeVI0MnMyOHk0RQ" \
  -d payment_id="8ddee625-d175-4c55-a5e0-5ed8c68e3cd1" \
  -d amount=100 \
  -d reason="requested_by_customer" \
  -d description="Refund for Order#33" \

The Crypto.com Pay API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to create a refund does not respond due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one refund is created.

Idempotent requests are not enabled by default, and it is available for refund API at the moment. To use this for a request, provide an additional Idempotency-Key: <key> header.

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. It is up to the merchant to define and create their own unique keys.

Webhooks

Webhooks make it easier to integrate with Crypto.com Pay by allowing you to subscribe to a set of events. You can subscribe to the events by going to your Merchant Dashboard and add a new webhook subscription.

When the event is sent to your webhook endpoint, the payload will include the resource object associated. You can refer to Resources for the schema of the objects.

Event Types

Webhook Endpoint

The webhook endpoint must return a 200 response code when it receives a Crypto.com Pay request.

If a 200 response code is not returned, we will retry the same request after 10 seconds until either we get a 200 response code, or we retried for 5 times (6 requests in total including the original one).

Webhook Signature

Crypto.com Pay signs the webhook events that sends to your endpoints. We do so by including a signature in each event’s Pay-Signature header. This allows you to verify that the events were sent by Crypto.com Pay, not by a third party.

Before you can verify signatures, you need to retrieve your endpoint’s Signature Secret from your Merchant Dashboard's Webhooks settings.

Each secret is unique to the endpoint to which it corresponds. If you use the same endpoint for both test and live API keys, note that the secret is different for each one. Additionally, if you use multiple endpoints, you must obtain a secret for each one.

Verifying signatures

The Pay-Signature header contains a timestamp and one or more signatures. The timestamp is prefixed by t=, and each signature is prefixed by a scheme. Schemes start with v1.

Pay-Signature: t=1492774577,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Crypto.com Pay generates signatures using a hash-based message authentication code (HMAC) with SHA-256. To prevent downgrade attacks, you should ignore all schemes that are not v1.

Step 1: Extract the timestamp and signatures from the header

Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair.

The value for the prefix t corresponds to the timestamp, and v1 corresponds to the signature(s). You can discard all other elements.

Step 2: Prepare the signed_payload string

You achieve this by concatenating the following in this exact order:

1. The timestamp (as a string)
2. The character .
3. The actual JSON payload (i.e. the request’s body)

1492774577.{"id":"920a4e24-169e-4205-85bd-348c1b834231","object_type":"event","type":"payment.created","created":1492774570,"data":{"object":{"id":"246dce08-019c-4bcb-871d-e8733295e027","amount":1900,"amount_refunded":0,"created":1492774570,"crypto_currency":"CRO","crypto_amount":"107.5","currency":"EUR","customer_id":null,"data_url":"https://pay.crypto.com/sdk/payments/246dce08-019c-4bcb-871d-e8733295e027","payment_url":"https://js.crypto.com/sdk/payments/checkout/set_wallet?publishableKey=XXX&id=246dce08-019c-4bcb-871d-e8733295e027&sdkMeta=YYY","return_url":null,"cancel_url":null,"description":"Test payment","live_mode":true,"metadata":{"customer_name":"Test","customer_email":"[email protected]"},"order_id":"Order ID","recipient":"Test","refunded":false,"status":"pending"}}}

Step 3: Determine the expected signature

Compute an HMAC with the SHA256 hash function. Use the endpoint’s Signature Secret as the key, and use the aforesaid concatenated string as the message.

Step 4: Compare signatures

Compare the signature in the header to the computed signature. If the signatures match, that means the webhook API request is indeed sent from Crypto.com Pay server, as there is no third party supposed to know the Signature Secret.

Additionally, you may compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

To protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures.

Troubleshooting

You can navigate to Merchant Dashboard -> Integrations -> Events page in order to view the events sent to your Webhooks and the response from your server.