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:
- Cronos (CRO)
- Bitcoin (BTC)
- Ethereum (ETH)
- Dogecoin (DOGE)
- Stable Coins (USDC)
- Other tokens supported by Crypto.com App and Crypto.com DeFi Swap
Please refer to this FAQ article for the full list of cryptocurrencies supported.
For information on available payout currencies for merchants, please see Payout.
Fees
Crypto.com Pay for Business has no transaction fee. For each payment from customers, merchants are guaranteed to receive the fiat currency amount they specified. The amount will be credited into the balance of the merchant account and can be withdrawn anytime.
When merchants request payout, a payout fee is applied. Please see Payout for more information.
Pay Rewards
Crypto.com Pay offers a Pay Rewards program to early or selected merchants. When customers pay using Crypto.com App and CRO, a CRO rebate will be provided to the customers. If the customers have eligible CRO stakes in their Crypto.com accounts, they can even enjoy 2x of the normal rebate rate.
Once you logged into the Merchant Dashboard, you can see the Pay Rewards percentage that your customers can earn.
Merchants should use the Promotion Banners to promote the rebate to their customers.
For information on Crypto.com Pay Rewards, please visit this FAQ article.
Refund
Merchants can refund all payments received either partially or in full.
For customers who pay using Crypto.com App, the refund will be sent back to their App account automatically. A preferred refund currency setting is available in App so that customers can select the cryptocurrency they want to receive for refunds.
For customers who pay using other cryptocurrency wallets, the payment page requires them to input their email addresses when they pay. When a refund is issued, a refund claim link and instruction will be sent to the email address provided for the customer to claim the refund. Subject to the refund method selected, a blockchain fee may be deducted from the refund amount.
Unresolved Payments
For customers who pay using other cryptocurrency wallets, the payment can be overpaid or underpaid. This is because there is no payment amount input check, and the cryptocurrency exchange rate could be updated when customers made the payment. The payment can also be late if the funds did not reach the provided wallet address in time.
If the payment is overpaid, the overpaid portion (with blockchain fee deducted) will be rebounded to the customer. On the merchant's end, the payment is still considered to be captured successfully.
If the payment is underpaid or late, the whole payment (with blockchain fee deducted) will be rebounded to the customer.
Similar to refund, a rebound fund claim link and instruction will be sent to the customer email address provided, so they can claim the rebound fund.
If the payment is sent using a cryptocurrency or network not supported by Crypto.com Pay, the funds will not be refunded or rebounded.
Merchant can navigate to Merchant Dashboard -> Payments -> Unresolved page to view these transactions. The claim links of the rebound fund can be found in the detailed view of each unresolved transaction.
Underpayment Threshold
To improve the user experience of on-chain payments and reduce the unnecessary network fees, merchants can decide a threshold of accepting payments from other cryptocurrency wallets even when those are underpaid.
The underpayment threshold can be set up in an absolute or relative (percentage) manner. Payments will be captured when they are within any of these two thresholds. Customers will not see these thresholds.
When a payment is underpaid and captured, the amount will be credited to the merchant account on a pro-rata basis. For example, if a customer paid 98 USDC for a payment with the amount of 100 USD, and it is within the threshold, then 98 USD will be credited to the merchant account.
Merchant can navigate to Merchant Dashboard -> Settings -> Payment page -> Underpayment Threshold to set up. This option is only enabled when the other cryptocurrency wallets payment option is enabled.
Payments paid using Crypto.com App will not be underpaid.
Merchant Acquirers
We welcome acquirers to help Crypto.com Pay onboard more merchants. Please contact [email protected] if you are interested.
Acquirers need to provide simple business information for each sub-merchant under their account, including an ID that the acquirer uses to refer to that sub-merchant.
When creating payments, the ID of the sub-merchants is required. It can also be retrieved back in our payment and refund APIs.
Creation of sub-merchants can be done through our Sub-merchant API or in the Merchant Dashboard.
Payouts
Crypto.com Pay for Business charges a payout fee for all payout settlements. A minimum blockchain transaction fee can be applied for very small settlement amount. Please login to Merchant Dashboard and check the payout page for more details.
For fiat currencies payout, a transmittance fee of may be applied depending on the intermediaries between your bank and our fiduciary partners. These are third parties that handle the wire transfer across countries and are outside of our control. Our fiduciary partners facilitate transfers to most of the international banks around the world.
Payout Currencies
Fiat Currencies
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:
You can always take a look at the Crypto.com Shop and see what it is like in the real world.
Get started by picking one of the following integration approaches, as simple as that!
Approach 1: Frontend and Backend Integration
Step 1: Register Crypto.com Pay Developer Access
Sign up for a Crypto.com Pay account, if you don't already have one.
Once you have access to the Crypto.com Pay Merchant Dashboard, You will be able to generate a secret key
and publishable key
pair. You should use the publishable key
in the Crypto.com Pay SDK and the secret key
when you directly interact with the Crypto.com Pay API.
Step 2: Add the Crypto.com Pay SDK Script
Add the script
<body>
<script src="https://js.crypto.com/sdk?publishable-key=YOUR_PUBLISHABLE_KEY_PLACEHOLDER"></script>
</body>
Add the following script to your web page. Replace the YOUR_PUBLISHABLE_KEY_PLACEHOLDER
with your Publishable Key.
Step 3: Create a Payment
Create payment
curl https://pay.crypto.com/api/payments \
-u YOUR_SECRET_KEY_PLACEHOLDER: \
-d amount=10000 \
-d currency=USD \
-d description="Product Name"
On server side, obtain a payment ID by creating a payment. Replace the YOUR_SECRET_KEY_PLACEHOLDER
with your Secret Key. If you use curl
, please note that a colon is needed after the Secret Key to prevent it from asking you for a password. A new payment is always pending to be captured. See Create a Payment for reference and the list of arguments you can pass in.
Response
{
// Showing seclected fields only
"id": "PAYMENT_UNIQUE_ID",
"amount": 10000,
"currency": "USD",
"description": "Product Name",
"status": "pending"
}
Step 4: Render the Crypto.com Pay Button
Render the button
<body>
<script
src="https://js.crypto.com/sdk?publishable-key=YOUR_PUBLISHABLE_KEY_PLACEHOLDER">
</script>
<script>
var paymentId = document.querySelector('#pay-button').dataset.paymentId
cryptopay.Button({
createPayment: function(actions) {
return actions.payment.fetch(paymentId)
},
onApprove: function(data, actions) {
// Optional: add logic such as browser redirection or check data object content
},
defaultLang: 'en-US' // Optional: default language for payment page
}).render("#pay-button")
</script>
<div id="pay-button" data-payment-id="PAYMENT_UNIQUE_ID"></div>
</body>
Add a container element on your page and render the Crypto.com Pay
button in it. Also pass the Payment ID
created in Step 3 into this container (attribute is data-payment-id
).
Then implement the createPayment
function. This function will be invoked when the customer clicks on the Crypto.com Pay
button. Since you already have a Payment ID
from Step 3, you just have to provide it and the SDK will not create another new payment.
Then implement the onApprove
function. You should add logic here to notify your server side which perform Step 5. Once Crypto.com Pay captures the payment, the checkout window will indicate that the payment has been captured and the onApprove
function will be called.
Step 5: Verify payment status
Retrieve the payment
curl https://pay.crypto.com/api/payments/PAYMENT_UNIQUE_ID \
-u YOUR_SECRET_KEY_PLACEHOLDER: \
On server side, retrieve the payment and check whether the payment status is succeeded
. See all the statuses here.
Approach 2: Frontend Only Integration
Step 1: Register Crypto.com Pay Developer Access
Sign up for a Crypto.com Pay account, if you don't already have one.
Once you have access to the Crypto.com Pay Merchant Dashboard, You will be able to generate a secret key
and publishable key
pair. You should be using the publishable key
in the Crypto.com Pay SDK and the secret key
when you directly interact with the Crypto.com Pay API .
Step 2: Add the Crypto.com Pay SDK Script
Add the script
<body>
<script src="https://js.crypto.com/sdk?publishable-key=YOUR_PUBLISHABLE_KEY_PLACEHOLDER"></script>
</body>
Add the following script to your web page. Replace the YOUR_PUBLISHABLE_KEY_PLACEHOLDER
with your Publishable Key.
Step 3: Render the Crypto.com Pay Button
Render the button
<body>
<script
src="https://js.crypto.com/sdk?publishable-key=YOUR_PUBLISHABLE_KEY_PLACEHOLDER">
</script>
<script>
cryptopay.Button({
createPayment: function(actions) {
return actions.payment.create({
currency: 'USD',
amount: 100,
description : 'Product Name',
order_id: 'sample-order-id',
metadata: {
size: 'XL',
color: 'black'
}
});
},
onApprove: function (data, actions) {
// Optional: add logic such as browser redirection or check data object content
},
defaultLang: 'en-US' // Optional: default language for payment page
}).render("#pay-button")
</script>
<div id="pay-button"></div>
</body>
Add a container element on your page and render the Crypto.com Pay
button in it.
Then implement the createPayment
function. This function will be invoked when the customer clicks on the Crypto.com Pay
button. The action.payment.create
function creates a new pending payment in the Crypto.com Pay server by providing details of the purchase as arguments. See Create a payment for reference and the list of arguments you can pass in.
Then implement the onApprove
function. Once Crypto.com Pay captures the payment, the checkout window will indicate that the payment has been captured and the onApprove
function will be called.
Checkout - Page Redirection
If you prefer a solution that has minimal impact to your user interface design, you may use your existing checkout interface, and redirect to Crypto.com payment page when customers submit your checkout form. Once the payment is made, the payment page will redirect back to your store to finish your order flow.
Step 1: Register Crypto.com Pay Developer Access
Sign up for a Crypto.com Pay account, if you don't already have one.
Once you have access to the Crypto.com Pay Merchant Dashboard, You will be able to generate a secret key
and publishable key
pair. You should use the secret key
when you directly interact with the Crypto.com Pay API.
Step 2: Create a Payment
Create payment
curl https://pay.crypto.com/api/payments \
-u YOUR_SECRET_KEY_PLACEHOLDER: \
-d amount=10000 \
-d currency=USD \
-d description="Product Name"
-d return_url="http://YOUR_WEBSITE.com/orders/123/complete"
-d cancel_url="http://YOUR_WEBSITE.com/orders/123/fail"
On server side, obtain a payment ID by creating a payment. Replace the YOUR_SECRET_KEY_PLACEHOLDER
with your Secret Key. If you use curl
, please note that a colon is needed after the Secret Key to prevent it from asking you for a password. A new payment is always pending to be captured. See Create a payment for reference and the list of arguments you can pass in.
It is a must for this flow to provide return_url
when creating payment. The payment returned will contain a payment_url
for the next step.
Response
{
// Showing seclected fields only
"id": "PAYMENT_UNIQUE_ID",
"amount": 10000,
"currency": "USD",
"description": "Product Name",
"status": "pending",
"payment_url": "https://js.crypto.com/sdk/payments/checkout/set_wallet?publishableKey=XXX&sdkMeta=YYY",
"return_url": "http://YOUR_WEBSITE.com/orders/123/complete",
"cancel_url": "http://YOUR_WEBSITE.com/orders/123/fail"
}
Step 3: Redirect to payment page
After creating the payment object, you will need to redirect customers to payment_url
to finish the payment. After the payment is paid, it will become succeeded
. The payment page will then redirect customers back to return_url
(or cancel_url
if there is any issue).
Step 4: Verify payment status
Retrieve the payment
curl https://pay.crypto.com/api/payments/PAYMENT_UNIQUE_ID \
-u YOUR_SECRET_KEY_PLACEHOLDER: \
On server side of your return_url
page, retrieve the payment and check whether the payment status is succeeded
. See all the statuses here.
Subscription - Button SDK
Generate the Crypto.com Pay Button and embedded it on your website. Once the button is clicked, there will be a popup for customers to complete the subscription authorization and payment of first billing period.
You will be able to see this on your checkout page:
Step 1: Register Crypto.com Pay Developer Access
Sign up for a Crypto.com Pay account, if you don't already have one.
Once you have access to the Crypto.com Pay Merchant Dashboard, You will be able to generate a secret key
and publishable key
pair. You should use the publishable key
in the Crypto.com Pay SDK and the secret key
when you directly interact with the Crypto.com Pay API.
Step 2: Add the Crypto.com Pay SDK Script
Add the script
<body>
<script src="https://js.crypto.com/sdk?publishable-key=YOUR_PUBLISHABLE_KEY_PLACEHOLDER"></script>
</body>
Add the following script to your web page. Replace the YOUR_PUBLISHABLE_KEY_PLACEHOLDER
with your Publishable Key.
Step 3: Create a Product and Pricing Plan
Create product and pricing plan
curl https://pay.crypto.com/api/products \
-u YOUR_SECRET_KEY_PLACEHOLDER: \
-H "Content-Type: application/json" \
-d '{
"name": "Newsletter monthly subscription",
"active": true,
"description": "Newsletter monthly subscription",
"metadata": {
"ref_id": "6936acde-1697-456d-95c1-0afcce047b29"
},
"pricing_plans": [
{
"amount": 1000,
"currency": "USD",
"active": true,
"description": "Newsletter monthly subscription pricing",
"interval": "month",
"interval_count": 1,
"metadata": {
"ref_id": "99213a90807b"
},
"purchase_type": "recurring"
}
]
}'
On server side, obtain a pricing plan ID by creating a product and its pricing plan. Replace the YOUR_SECRET_KEY_PLACEHOLDER
with your Secret Key. See Create a Product section for the schema of product and pricing plan objects that you should pass in.
You can also use the pricing plan ID of a pricing plan you created previously.
Response
{
"id": "89630fd4-e900-40c9-a072-758f16d9dbdd",
"account_id": "a5b1e789-fc2b-478b-a0be-3fbbc2607563",
"active": true,
"description": "Newsletter monthly subscription",
"name": "Newsletter monthly subscription",
"metadata": {
"ref_id": "6936acde-1697-456d-95c1-0afcce047b29"
},
"created_at": 1628000625,
"updated_at": 1628000625,
"pricing_plans": [
{
"id": "2506cad4-fed6-49c0-98f5-34b0bedd6891",
"active": true,
"amount": 1000,
"currency": "USD",
"interval": "month",
"interval_count": 1,
"purchase_type": "recurring",
"description": "Newsletter monthly subscription pricing",
"metadata": {
"ref_id": "99213a90807b"
},
"created_at": 1628000625,
"updated_at": 1628000625,
}
]
}
Step 4: Create a Customer
Create customer
curl https://pay.crypto.com/api/customers \
-u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ: \
-H "Content-Type: application/json" \
-d '{
"ref_id": "6ded84e75449",
"name": "John Doe"
}'
Similarly, on server side, obtain a customer ID by creating a customer. See Create a Customer section for the schema of customer object that you should pass in.
You can also use the customer ID of a customer you created previously.
Response
{
"id": "8e384561-d781-4868-9b66-3fb2d7a83ba5",
"email": null,
"ref_id": "6ded84e75449",
"name": "John Doe",
"created_at": 1627917897,
"updated_at": 1627917897
}
Step 5: Create a Subscription
Create subscription
curl https://pay.crypto.com/api/subscriptions \
-u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ: \
-H "Content-Type: application/json" \
-d '{
"customer_id": "8e384561-d781-4868-9b66-3fb2d7a83ba5",
"billing_cycle_anchor": 1625943925,
"interval": "month",
"metadata": {
"ref_id": "34196851011b"
},
"items": [
{
"plan_id": "2506cad4-fed6-49c0-98f5-34b0bedd6891",
"quantity": 1
}
]
}'
With customer ID and pricing plan ID, now you can create a subscription object. You also need to provide a billing_cycle_anchor
which is the starting time of your billing cycle. See Create a Subscription section for the schema of subscription object that you should pass in.
Response
{
"id": "SUBSCRIPTION_UNIQUE_ID",
"created_at": 1625943925,
"currency": "USD",
"amount": 1000,
"current_period_end": 1628622325,
"current_period_start": 1625943925,
"auto_end_at": null,
"ended_at": null,
"cancelled_at": null,
"interval": "month",
"interval_count": 1,
"live_mode": true,
"metadata": {
"ref_id": "34196851011b"
},
"note": null,
"recipient": "Crypto.com Shop",
"reference": null,
"status": "pending",
"updated_at": 1625943925
}
Step 6: Render the Crypto.com Pay Button
Render the button
<body>
<script
src="https://js.crypto.com/sdk?publishable-key=YOUR_PUBLISHABLE_KEY_PLACEHOLDER">
</script>
<script>
var subscriptionId = document.querySelector('#pay-button').dataset.subscriptionId;
cryptopay.Button({
createSubscription: function(actions) {
return actions.subscription.fetch(subscriptionId);
},
onApprove: function(data, actions) {
// Optional: add logic such as browser redirection or check data object content
},
defaultLang: 'en-US' // Optional: default language for payment page
}).render("#pay-button")
</script>
<div id="pay-button" data-subscription-id="SUBSCRIPTION_UNIQUE_ID"></div>
</body>
Add a container element on your page and render the Crypto.com Pay
button in it. Also pass the Subscription ID
created in Step 5 into this container (attribute is data-subscription-id
).
Then implement the createSubscription
function. This function will be invoked when the customer clicks on the Crypto.com Pay
button. Since you already have a Subscription ID
from Step 3, you just have to provide it and the SDK will not create another new payment.
Then implement the onApprove
function. You should add logic here to show the success message. Once Crypto.com Pay got your customer's payment authorization on the subscription, the onApprove
function will be called.
Step 7: Verify subscription status
Retrieve the subscription
curl https://pay.crypto.com/api/subscriptions/SUBSCRIPTION_UNIQUE_ID \
-u YOUR_SECRET_KEY_PLACEHOLDER:
On server side of your return_url
page, retrieve the subscription and check whether the subscription status is active
. See all the statuses here.
Step 8: Monitor events
After the subscription turned into active
, it will collect payment for the first billing period right away. Invoice objects and its associated payment objects will be created automatically for each billing period. Cryptocurrency payment will be collect from customer's Crypto.com App automatically based on the currency setting they used when they approved the subscription.
You should monitor invoice.paid
and invoice.payment_attempt_failed
events for your subscriptions. Please refer to Webhooks for more details.
Subscription - Page Redirection
If you prefer a solution that has minimal impact to your user interface design, you may use your existing checkout interface, and redirect to Crypto.com subscription payment page when customers submit your checkout form. Once the subscription approval is made, the subscription payment page will redirect back to your store to finish your order flow.
Step 1: Register Crypto.com Pay Developer Access
Sign up for a Crypto.com Pay account, if you don't already have one.
Once you have access to the Crypto.com Pay Merchant Dashboard, You will be able to generate a secret key
and publishable key
pair. You should use the publishable key
in the Crypto.com Pay SDK and the secret key
when you directly interact with the Crypto.com Pay API.
Step 2: Create a Product and Pricing Plan
Create product and pricing plan
curl https://pay.crypto.com/api/products \
-u YOUR_SECRET_KEY_PLACEHOLDER: \
-H "Content-Type: application/json" \
-d '{
"name": "Newsletter monthly subscription",
"active": true,
"description": "Newsletter monthly subscription",
"metadata": {
"ref_id": "6936acde-1697-456d-95c1-0afcce047b29"
},
"pricing_plans": [
{
"amount": 1000,
"currency": "USD",
"active": true,
"description": "Newsletter monthly subscription pricing",
"interval": "month",
"interval_count": 1,
"metadata": {
"ref_id": "99213a90807b"
},
"purchase_type": "recurring"
}
]
}'
On server side, obtain a pricing plan ID by creating a product and its pricing plan. Replace the YOUR_SECRET_KEY_PLACEHOLDER
with your Secret Key. See Create a Product section for the schema of product and pricing plan objects that you should pass in.
You can also use the pricing plan ID of a pricing plan you created previously.
Response
{
"id": "89630fd4-e900-40c9-a072-758f16d9dbdd",
"account_id": "a5b1e789-fc2b-478b-a0be-3fbbc2607563",
"active": true,
"description": "Newsletter monthly subscription",
"name": "Newsletter monthly subscription",
"metadata": {
"ref_id": "6936acde-1697-456d-95c1-0afcce047b29"
},
"created_at": 1628000625,
"updated_at": 1628000625,
"pricing_plans": [
{
"id": "2506cad4-fed6-49c0-98f5-34b0bedd6891",
"active": true,
"amount": 1000,
"currency": "USD",
"interval": "month",
"interval_count": 1,
"purchase_type": "recurring",
"description": "Newsletter monthly subscription pricing",
"metadata": {
"ref_id": "99213a90807b"
},
"created_at": 1628000625,
"updated_at": 1628000625,
}
]
}
Step 3: Create a Customer
Create customer
curl https://pay.crypto.com/api/customers \
-u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ: \
-H "Content-Type: application/json" \
-d '{
"ref_id": "6ded84e75449",
"name": "John Doe"
}'
Similarly, on server side, obtain a customer ID by creating a customer. See Create a Customer section for the schema of customer object that you should pass in.
You can also use the customer ID of a customer you created previously.
Response
{
"id": "8e384561-d781-4868-9b66-3fb2d7a83ba5",
"email": null,
"ref_id": "6ded84e75449",
"name": "John Doe",
"created_at": 1627917897,
"updated_at": 1627917897
}
Step 4: Create a Subscription
Create subscription
curl https://pay.crypto.com/api/subscriptions \
-u sk_test_7ETNLmgFVsmmdiEhfqwjHPeJ: \
-H "Content-Type: application/json" \
-d '{
"customer_id": "8e384561-d781-4868-9b66-3fb2d7a83ba5",
"return_url": "http://YOUR_WEBSITE.com/orders/123/complete",
"billing_cycle_anchor": 1625943925,
"interval": "month",
"metadata": {
"ref_id": "34196851011b"
},
"items": [
{
"plan_id": "2506cad4-fed6-49c0-98f5-34b0bedd6891",
"quantity": 1
}
]
}'
With customer ID and pricing plan ID, now you can create a subscription object. You also need to provide a billing_cycle_anchor
which is the starting time of your billing cycle. See Create a Subscription section for the schema of subscription object that you should pass in.
It is a must for this flow to provide return_url
when creating subscription. The subscription returned will contain a subscription_url
for the next step.
Response
{
"id": "SUBSCRIPTION_UNIQUE_ID",
"created_at": 1625943925,
"currency": "USD",
"amount": 1000,
"current_period_end": 1628622325,
"current_period_start": 1625943925,
"auto_end_at": null,
"ended_at": null,
"cancelled_at": null,
"interval": "month",
"interval_count": 1,
"live_mode": true,
"metadata": {
"ref_id": "34196851011b"
},
"note": null,
"recipient": "Crypto.com Shop",
"reference": null,
"return_url": "http://YOUR_WEBSITE.com/orders/123/complete",
"subscription_url": "https://js.crypto.com/subscription?publishableKey=XXXsdkMeta=YYY",
"status": "pending",
"updated_at": 1625943925
}
Step 5: Redirect to payment page
After creating the subscription object, you will need to redirect customers to subscription_url
to finish the payment authorization. After the payment is authorized, the subscription will become active
. The payment page will then redirect customers back to return_url
(or cancel_url
if there is any issue).
Step 6: Verify subscription status
Retrieve the subscription
curl https://pay.crypto.com/api/subscriptions/SUBSCRIPTION_UNIQUE_ID \
-u YOUR_SECRET_KEY_PLACEHOLDER:
On server side of your return_url
page, retrieve the subscription and check whether the subscription status is active
. See all the statuses here.
Step 7: Monitor events
After the subscription turned into active
, it will collect payment for the first billing period right away. Invoice objects and its associated payment objects will be created automatically for each billing period. Cryptocurrency payment will be collect from customer's Crypto.com App automatically based on the currency setting they used when they approved the subscription.
You should monitor invoice.paid
and invoice.payment_attempt_failed
events for your subscriptions. Please refer to Webhooks for more details.
Promotion Banner SDK
The Crypto.com Pay promotion banners are an effective way to let customers be aware of the Crypto.com Pay payment option. These banners are often presented at the upstream of the shopping journey (e.g. shop home page, the product details pages).
If you are eligible for the Pay Rewards program, you can use the banners to drive more sales by letting your customers know that they can pay with crypto to earn rebates.
When your customers clicked the banners, there will be a popup with high-level checkout steps to guide them to pay using Crypto.com Pay.
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:
|
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. |
string | ||
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 |
---|---|---|
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:
- The timestamp (as a string)
- The character
.
- 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.