NAV
shell javascript

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, Cronos PoS 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:

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

Currency Minimum Settlement Amount
USD 100 USD
EUR* 130 EUR
AUD 150 AUD

* 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

Currency Minimum Settlement Amount Transfer Done via
Bitcoin (BTC) 0.01 BTC Bitcoin blockchain
Ethereum (ETH) 0.1 ETH Ethereum network
Cronos (CRO) 500 CRO Ethereum network
USD Coin (USDC) 100 USDC Ethereum network

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:

alt text

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:

alt text

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.

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

Name Type Description
theme string Combination of the background color and font color for the promotion banner.

Possible values: black-font-on-grey (default), black-font-on-transparent, black-font-on-white, white-font-on-grey, white-font-on-transparent.
size string Size of the promotion banner.

Possible values: small, medium (default), large, fit-width (i.e. adapting the banner's width to the container).
font string Font of the promotion banner.

Possible values: sf pro text (default), arial, helvetica, roboto.
bannerMessage string Message of the promotion banner.

Possible values: earn-rebate (default), shop-now.
targetNodes string,
string array,
HTMLElement, or
HTMLElement array
The identifier of container element(s) that the banner will be rendered in, e.g., '.crypto-pay-banner'.

Possible values:
  1. '.class-name': To identify the container element by class.
  2. '#id-name': To identify the container elemen by id.
  3. ['.class-name','#id-name']: To identify the container element by both class and id.
Note: HTMLElement and HTMLElement list are also supported.

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:

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.

Status Code Meaning
200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided.
402 - Request Failed The parameters were valid but the request failed.
404 - Not Found The requested resource doesn't exist.
429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors Something went wrong on Crypto.com Pay's end.

Attributes

Attribute Type Description
type string The type of error returned. One of authentication_error, invalid_request_error, or rate_limit_error.
code string For some errors that could be handled programmatically, a short string indicating the error code reported.
param string If the error is parameter-specific, the parameter related to the error.

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

Name Type Description
id string Unique identifier for the object.
amount positive integer A positive integer representing how much to collect in the smallest currency unit (e.g., 100 cents to collect $1.00).

Refer to Pricing Currencies for the smallest unit for each currency.

Refer to Minimum Pricing Amount for the minimum amount for each pricing currency.
currency currency Three-letter currency code for the payment amount (pricing currency). Must be a supported fiat currency / cryptocurrency.

Refer to Pricing Currencies for the currency code.
amount_refunded positive integer or zero Amount in cents refunded (can be less than the amount of the payment if a partial refund was issued).
created timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
crypto_currency string The cryptocurrency to be collected for this payment.
crypto_amount string The amount of cryptocurrency to be collected for this payment.
customer_id string ID of the customer created in Crypto.com Pay Merchant Dashboard, if exists.
payment_url string The URL of the payment page that customers will navigate to in order to make the payment.
return_url string The URL for payment page to redirect back to when the payment becomes succeeded.
cancel_url string The URL for payment page to redirect to when the payment is failed or cancelled.
description string An arbitrary string attached to the object.
live_mode boolean Has the value true if the object exists in live mode or the value false if the object exists in test mode.
metadata hash Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
order_id string Merchant provided order ID for this payment. Merchants can view the associated order ID of each payment on the Merchant Dashboard. Crypto.com Pay does not verify or guarantee the uniqueness of the values in this field.
recipient string The name of the merchant collecting this payment.
refunded boolean Whether the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false.
status string The status of the payment is either pending (pending payment), succeeded (payment captured), or cancelled.
payment_source string Whether the payment is paid from Crypto.com Wallet App or External Wallets.
payment_type string Whether the payment is about checkout or invoice.
sub_merchant_id string ID of the sub-merchant associated with this payment. It is required for merchant acquirers.
expired_at timestamp Time at which the payment expires. Measured in seconds since the Unix epoch.

Pricing Currencies

Supported Pricing Currencies (Fiat)

ISO Currency Code Smallest Unit Example Pricing Amount Payment Object's amount Value
USD 0.01 100 USD 10000
EUR 0.01 100 EUR 10000
AUD 0.01 100 AUD 10000
CAD 0.01 100 CAD 10000
GBP 0.01 100 USD 10000
BGN 0.01 100 BGN 10000
BRL 0.01 100 BRL 10000
CHF 0.01 100 CHF 10000
CLP 1 100 CLP 100
CNY 0.01 100 CNY 10000
COP 0.01 100 COP 10000
DKK 0.01 100 DKK 10000
HKD 0.01 100 HKD 10000
IDR 0.01 100 IDR 10000
INR 0.01 100 INR 10000
JPY 1 100 JPY 100
KRW 1 100 KRW 100
MDL 0.01 100 MDL 10000
MOP 0.01 100 MOP 10000
MXN 0.01 100 MXN 10000
MYR 0.01 100 MYR 10000
NOK 0.01 100 NOK 10000
PHP 0.01 100 PHP 10000
RON 0.01 100 RON 10000
RUB 0.01 100 RUB 10000
SAR 0.01 100 SAR 10000
SEK 0.01 100 SEK 10000
SGD 0.01 100 SGD 10000
THB 0.01 100 THB 10000
TRY 0.01 100 TRY 10000
TWD 0.01 100 TWD 10000
UAH 0.01 100 UAH 10000
ZAR 0.01 100 ZAR 10000

Supported Pricing Currencies (Crypto)

Currency Code Smallest Unit Example Pricing Amount Payment Object's amount Value
BTC satoshi
(1 × 10-8)
1 BTC 100000000
ETH wei
(1 × 10-18)
0.5 ETH 500000000000000000
CRO (1 × 10-18) 10 CRO 10000000000000000000

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

Parameter Required Description
amount required A positive integer representing how much to collect in the smallest currency unit (e.g., 100 cents to collect $1.00).

Refer to Pricing Currencies for the smallest unit for each currency.
currency required Three-letter currency code for the payment amount (pricing currency). Must be a supported fiat currency / cryptocurrency.

Refer to Pricing Currencies for the currency code.
description optional An arbitrary string attached to the object.
metadata optional Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
order_id optional Merchant provided order ID for this payment. Merchants can view the associated order ID of each payment on the Merchant Dashboard. Crypto.com Pay does not verify or guarantee the uniqueness of the values in this field.
return_url optional The URL for payment page to redirect back to when the payment becomes succeeded. It is required for redirection flow.
cancel_url optional The URL for payment page to redirect to when the payment is failed or cancelled.
sub_merchant_id optional ID of the sub-merchant associated with this payment. It is required for merchant acquirers.
onchain_allowed optional Whether to allow the customer to pay by Other Cryptocurrency Wallets for this payment. If not specified, the setting in merchant account will be used.
expired_at optional Time at which the payment expires. Measured in seconds since the Unix epoch. If not specified, it will expire after the default period (10 minutes).

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

Parameter Required Description
id required The identifier of the payment to be retrieved.

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

Parameter Required Description
id required The identifier of the payment to be cancelled.

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

Parameter Required Description
created_at_begin optional Filter by payment created time. Measured in seconds since the Unix epoch.
created_at_end optional Filter by payment created time. Measured in seconds since the Unix epoch.
captured_at_begin optional Filter by payment captured time. Measured in seconds since the Unix epoch.
captured_at_end optional Filter by payment captured time. Measured in seconds since the Unix epoch.
per_page optional Number of payments to be listed per page (10 - 100).
page optional Current page number.

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

Name Type Description
id string Unique identifier for the refund object.
payment_id string Unique identifier for the payment object.
amount positive integer A positive integer representing how much to collect in the smallest currency unit (e.g., 100 cents to collect $1.00).

Refer to Pricing Currencies for the smallest unit for each currency.
currency currency Three-letter currency code for the payment amount (pricing currency). Must be a supported fiat currency / cryptocurrency.

Refer to Pricing Currencies for the currency code.
debit_currency string The currency of funds being deducted from merchant account for this refund.
debit_amount positive integer The amount of funds being deducted from merchant account for this refund.
description string An arbitrary string attached to the object.
reason string Reason for the refund. If set via Merchant Dashboard, possible values are Duplicate, Fraudulent, and Requested by customer.
created timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
onchain_email_last_sent_at timestamp If the payment is paid from external wallets, this stores the time when the refund email has been sent to the customer.
onchain_wallet_provided_at timestamp If the payment is paid from external wallets, this stores the time when the customer input their refund destination.
transferred_at timestamp Time when the refund is transferred.
refund_currency string The cryptocurrency to be refunded
refund_amount positive integer The amount of cryptocurrency to be refunded.
refund_destination string Whether the refund is sent to Crypto.com Wallet App or External Wallets.
status string The status of the refund is either pending, prepared (refund destination is not known and therefore not transferred yet), succeeded (transferred), cancelled, failed and done.
sub_merchant_id string ID of the sub-merchant associated with this payment.

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

Parameter Required Description
payment_id required Unique identifier for the payment object.
amount required positive integer
reason optional Reason for the refund. If set, possible values are duplicate, fraudulent, and requested_by_customer.
description optional An arbitrary string attached to the object.

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

Parameter Required Description
id required The identifier of the refund to be retrieved.

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

Parameter Required Description
payment_id required The identifier of the payment to be retrieved.

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

Name Type Description
id string Unique identifier for the rebound object.
payment_id string Unique identifier for the payment object.
created_at timestamp Time at which the rebound was created. Measured in seconds since the Unix epoch.
onchain_email_last_sent_at timestamp The time when the refund email has been sent to the customer.
onchain_wallet_provided_at timestamp The time when the customer input their refund destination.
transferred_at timestamp Time when the rebound fund is transferred.
crypto_currency string The cryptocurrency to be rebounded.
crypto_amount string The amount of cryptocurrency to be rebounded.
destination string Whether the rebound is sent to Crypto.com Wallet App or External Wallets.
reason string Reason of rebound.
status string The status of the rebound is either pending (refund destination is known), withdraw_requested (transferring), completed or rejected.

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

Parameter Required Description
payment_id required The identifier of the payment to be retrieved.

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

Name Type Description
id string Unique identifier for the object.
email string Email
ref_id string Merchant reference identifier of the customer
name string Name of the customer
created_at timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
updated_at timestamp Time at which the object was last updated. Measured in seconds since the Unix epoch.

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

Name Required Description
email optional Email address of the customer (required for email invoice feature, optional for subscription)
ref_id optional Merchant reference identifier of the customer (required if email is not provided)
name required Name of the customer

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

Parameter Required Description
id required The identifier of the customer to be retrieved.

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

Parameter Required Description
per_page optional Number of payments to be listed per page (10 - 100).
page optional Current page number.

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

Name Type Description
id string Unique identifier for the object.
name string Name of the product.
active boolean Whether the product is active.
description string An arbitrary string attached to the object.
metadata hash Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
pricing_plans Array Array of pricing plan for the product.
created_at timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
updated_at timestamp Time at which the object was last updated. Measured in seconds since the Unix epoch.

Attributes - Pricing Plan

Name Type Description
id string Unique identifier for the object.
amount positive integer A positive integer representing how much to collect in the smallest currency unit (e.g., 100 cents to collect $1.00).

Refer to Pricing Currencies for the smallest unit for each currency.
currency currency Three-letter currency code for the payment amount (pricing currency). Must be a supported fiat currency / cryptocurrency.

Refer to Pricing Currencies for the currency code.
active boolean Whether the product is active.
description string An arbitrary string attached to the object.
interval string Interval period of recurring pricing plan. Only supports month at the moment.
interval_count positive integer Count of the period for each interval (e.g. 1 means the subscription is paid every one month)
metadata hash Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
purchase_type string Whether the pricing is recurring or one_time.
created_at timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
updated_at timestamp Time at which the object was last updated. Measured in seconds since the Unix epoch.

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

Name Required Description
name required Name of the product.
active optional Whether the product is active.
description optional An arbitrary string attached to the object.
metadata optional Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
pricing_plans required Array of pricing plan for the product.

Attributes - Pricing Plan

Name Type Description
id string Unique identifier for the object.
amount positive integer A positive integer representing how much to collect in the smallest currency unit (e.g., 100 cents to collect $1.00).

Refer to Pricing Currencies for the smallest unit for each currency.
currency currency Three-letter currency code for the payment amount (pricing currency). Must be a supported fiat currency / cryptocurrency.

Refer to Pricing Currencies for the currency code.
active boolean Whether the product is active.
description string An arbitrary string attached to the object.
interval string Interval period of recurring pricing plan. Only supports month at the moment.
interval_count positive integer Count of the period for each interval (e.g. 1 means the subscription is paid every one month)
metadata hash Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
purchase_type string Whether the pricing is recurring or one_time.
created_at timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
updated_at timestamp Time at which the object was last updated. Measured in seconds since the Unix epoch.

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

Parameter Required Description
id required The identifier of the product to be retrieved.

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

Parameter Required Description
per_page optional Number of payments to be listed per page (10 - 100).
page optional Current page number.

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

Name Type Description
id string Unique identifier for the object.
amount positive integer A positive integer representing how much to collect in the smallest currency unit (e.g., 100 cents to collect $1.00).

Refer to Pricing Currencies for the smallest unit for each currency.
currency currency Three-letter currency code for the payment amount (pricing currency). Must be a supported fiat currency / cryptocurrency.

Refer to Pricing Currencies for the currency code.
current_period_start timestamp The starting time of current billing period. Measured in seconds since the Unix epoch.
current_period_end timestamp The ending time of current billing period. Measured in seconds since the Unix epoch.
auto_end_at timestamp The preset ending time of the subscription, null if the subscription does not end automatically. Measured in seconds since the Unix epoch.
ended_at timestamp The ending time of the subscription if it is ended. Measured in seconds since the Unix epoch.
cancelled_at timestamp The cancelling time of the subscription if it has been cancelled by either merchant or customer.
interval string Interval period of recurring pricing plan. Only supports month at the moment.
interval_count positive integer Count of the period for each interval (e.g. 1 means the subscription is paid every one month)
live_mode boolean Has the value true if the object exists in live mode or the value false if the object exists in test mode.
metadata hash Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
note string An arbitrary string attached to the object. Will be displayed at the bottom of subscription payment page.
reference string An arbitrary string attached to the object for internal use.
recipient string The name of the merchant collecting this payment.
subscription_url string The URL of the subscription payment page which customers will navigate to in order to approve the subscription payment.
return_url string The URL for subscription payment page to redirect back to when the subscription authorization becomes succeeded.
status string The status of the subscription is either pending (pending payment authorization), active, expired (ended after preset subscription period) or cancelled (cancelled by either merchant or customer).
created_at timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
updated_at timestamp Time at which the object was last updated. Measured in seconds since the Unix epoch.

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

Parameter Required Description
customer_id required The identifier of the customer for this subscription.
billing_cycle_anchor required The starting time of billing cycle. Measured in seconds since the Unix epoch.
items required An array of pricing plan identifiers and their respective quantity for this subscription.
metadata optional Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
return_url optional The URL for subscription payment page to redirect back to when the subscription authorization becomes succeeded. It is required for redirection flow.

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

Parameter Required Description
id required The identifier of the subscription to be retrieved.

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

Parameter Required Description
id required The identifier of the subscription to be cancelled.

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

Parameter Required Description
per_page optional Number of subscriptions to be listed per page (10 - 100).
page optional Current page number.

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

Name Type Description
id string Unique identifier for the object.
amount_fractional positive integer A positive integer representing how much to collect in the smallest currency unit (e.g., 100 cents to collect $1.00).

Refer to Pricing Currencies for the smallest unit for each currency.
currency currency Three-letter currency code for the payment amount (pricing currency). Must be a supported fiat currency / cryptocurrency.

Refer to Pricing Currencies for the currency code.
status string The status of the payment is either draft, outstanding, expired, paid, failed.
customer Customer Customer for this invoice.
note string An arbitrary string attached to the object.
subscription_id string Unique identifier for the associated subscription object, if applicable.

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

Name Type Description
id string Unique identifier for the object.
external_id string Acquirer's reference identifier of the sub-merchant.

It cannot contain characters other than letters, numbers and underscores.
name string Name of the sub-merchant.
business_settings Array Business settings of the sub-merchant.
support_email string Support email address of the sub-merchant.
active boolean Whether the sub-merchant is active.
cashback_rate decimal The Pay Rewards rate we offer for this sub-merchant's customers. Read Only.
created_at timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
updated_at timestamp Time at which the object was last updated. Measured in seconds since the Unix epoch.
live_account_enabled boolean Whether the sub-merchant is enabled for processing payments.
avatar string URL of the sub-merchant's logo.

Attributes - Business Settings

Name Type Description
website string URL of the sub-merchant's website.
legal_entity_name string Legal entity name of the sub-merchant.
business_category string Type of the sub-merchant's business.

Possible values: corporation, individual_or_sole_proprietorship, partnership, other.
country string The 2-digit ISO country code of the sub-merchant's business country, e.g., US for United States of America, and CA for Canada.
business_industry string The 4-digit ISO Merchant Category Code (MCC) of the sub-merchant's business, e.g., 5691 for Men’s and Women’s Clothing Stores.
registration_number string Business registration number of the sub-merchant.
business_address string Address line 1 for the sub-merchant's business address.
business_address2 string Address line 1 for the sub-merchant's business address.
province string Town / City of the sub-merchant's business address.
region string State / County / Region of the sub-merchant's business address.
zip_code string Postalcode / Zip Code of the sub-merchant's business address.
service_region string Regions in which the sub-merchant’s product and/or service is available (separated by comma ',').

Possible values: Global, Asia, Africa, Europe, Oceania, North America, South America, Antarctica.

Example: Asia, Europe.
service_country string The 2-digit ISO country codes in which the sub-merchant's product and/or service is available (separated by comma ','). It shall be within the service_region.

Blank if service_region is Global.

Example: CN,HK,JP.

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

Name Required Description
external_id required Acquirer's reference identifier of the sub-merchant.

It cannot contain characters other than letters, numbers and underscores.
name required Name of the sub-merchant.
support_email required Support email address of the sub-merchant.
business_settings required Business settings of the sub-merchant.
avatar optional The sub-merchant logo file.

Attributes - Business Settings

Name Required Description
legal_entity_name required Legal entity name of the sub-merchant.
business_category required Type of the sub-merchant's business.

Possible values: corporation, individual_or_sole_proprietorship, partnership, other.
country required The 2-digit ISO country code of the sub-merchant's business country, e.g., US for United States of America, and CA for Canada.
business_industry required The 4-digit ISO Merchant Category Code (MCC) of the sub-merchant's business, e.g., 5691 for Men’s and Women’s Clothing Stores.
registration_number required Business registration number of the sub-merchant.
business_address required Address line 1 for the sub-merchant's business address.
business_address2 optional Address line 1 for the sub-merchant's business address.
province required Town / City of the sub-merchant's business address.
region required State / County / Region of the sub-merchant's business address.
zip_code required Postalcode / Zip Code of the sub-merchant's business address.
website optional URL of the sub-merchant's website.
service_region optional Regions in which the sub-merchant’s product and/or service is available (separated by comma ',').

Possible values: Global, Asia, Africa, Europe, Oceania, North America, South America, Antarctica.

Example: Asia, Europe.
service_country optional The 2-digit ISO country codes in which the sub-merchant's product and/or service is available (separated by comma ','). It shall be within the service_region.

Blank if service_region is Global.

Example: CN,HK,JP.

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

Parameter Required Description
id required The identifier of the sub-merchant to be retrieved.

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

Parameter Required Description
per_page optional Number of payments to be listed per page (10 - 100).
page optional Current page number.

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. Please verify the ID and details of the resource, and also the signature to ensure that you are consuming the correct event.

You can refer to Resources for the schema of the objects.

Event Types

Event Description
payment.created New payment is created
payment.fulfill Payment is available for capture
payment.captured Payment has been captured (i.e. status has become succeeded)
payment.refund_requested New refund is requested by merchant
payment.refund_transferred Refund has been transferred to customer
subscription.created New subscription is created
subscription.activated Subscription is activated by customer
subscription.cancelled Subscription has been cancelled
invoice.created Invoice is created (either individually or by recurring invoices, subscriptions)
invoice.paid Invoice is paid
invoice.payment_attempt_failed The payment attempted for the invoice is failed (usually used to handle failed automatic payment attempts like subscriptions)

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.