Overview

Home

Welcome to Crypto.com Pay Checkout! Here you can find out how you can adopt the best way to accept crypto and be paid in fiat.

Crypto.com Pay Checkout is a feature of Crypto.com Pay, which utilises Crypto.com Chain as a high performing native blockchain solution. This enables the transaction flows between crypto users and merchants seamless, cost-efficient and secure.

You can read more about Crypto.com Chain here.

Accepting Payments

Payment Methods

Crypto.com Pay Checkout generates a QR code embedded with payment information on behalf of the merchants. A customer can scan this QR code using the Crypto.com App, available on iOS and Android.

A Crypto.com App user can simply use the in-app scanner to scan the QR code and complete the transaction by paying cryptocurrency.

Payment Currencies

Crypto.com Pay Checkout currently accepts the following cryptocurrencies:

Crypto.com Coin (CRO)
Bitcoin (BTC)
Ethereum (ETH)
Ripple (XRP)
Litecoin (LTC)

Behind the scene, given that Crypto.com Pay utilises Crypto.com Chain, all transactions must be performed using its native token, CRO. Therefore, when the customers choose any cryptocurrencies other than CRO, Crypto.com Pay will exchange the chosen cryptocurrency into CRO on behalf of the customers.

For information on settlement currencies, please see Settlement Currencies.

Fees

Crypto.com Pay Checkout is free of charge for merchants. Merchants are guaranteed to receive the amount in the desired fiat currency, which will be shown on the Merchant Dashboard.

However, depending on the currency, settlement fees may be applied when you transfer the funds to your bank account. Please see Settlements for more information.

Cashback

Merchants are not entitled to cashback incentives provided by Crypto.com Chain. Instead, the cashback incentives are granted to the customers as Crypto.com Pay Rewards when they choose to pay in CRO.

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

Refund

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

Settlements

Crypto.com Pay Checkout charges a 0.5% fee for all settlements.

Settlement Currencies

Fiat

US Dollars (USD)

Minimum settlement amount is 1000 USD.

On top of the settlement fee, 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.

Euros (EUR)

Minimum settlement amount is 20 EUR.

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

Cryptocurrency

Coming soon.

Integration Guides

Generate the Crypto.com Pay Checkout Button on the Merchant Dashboard and embedded it on your website.

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!

Javascript SDK

Approach 1: Frontend and Backend Integration (Recommended)

Step 1: Register Crypto.com Pay Developer Access

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 Checkout SDK and the secret key when you directly interact with the Crypto.com Pay API .

Step 2: Add the Crypto.com Pay Checkout 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=100 \
  -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. Please note that a colon is needed after the Secret Key to prevent curl from asking you for a password. A new payment is always a 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) {
        // TODO: logic to trigger your server to verify payment status via Crypto.com Pay API (Step 5)
      }
    }).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 Checkout 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.

Once the Crypto.con Pay Checkout button has been clicked, a checkout window with a QR code will be launched. Customer can use the Crypto.com Wallet App to scan the QR code and initiates the payment approval process.

Then implement the onApproved function. This function will be invoked when the customer scans the QR code using his or her Crypto.com Wallet App. You should add logic here to notify your server side to perform Step 5.

Once Crypto.com Pay approves the payment, the checkout window will indicate that the payment has been approved 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 payment status is succeeded. See all the statuses here.

Approach 2: Frontend Only Integration

Step 1: Register Crypto.com Pay Developer Access

Step 2: Add the Crypto.com Pay Checkout 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
      }
    }).render("#pay-button")
  </script>

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

Add a container element on your page and render the Crypto.com Pay Checkout button in it.
Then implement the createPayment function. This function will be invoked when the customer clicks on the Crypto.com Pay Checkout 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 onApproved function. This function will be invoked when the customer scans the QR code using his or her Crypto.com Wallet App.

Once Crypto.com Pay approves the payment, the checkout window will indicate that the payment has been approved and the onApprove function will be called.

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:

WooCommerce

Opencart

Ecwid

nopCommerce

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

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 subjects to breaking changes, use it with your own Risk.

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.
409 - Conflict	The request conflicts with another request (perhaps due to using the same idempotent key).
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 create a Payment object. You can retrieve and refund individual payments as well as list all payments. Payments are identified by a unique, random 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,
  "data_url": "https://pay.crypto.com/sdk/payments/fa176d2e-8f58-419d-a531-e2c8e4dc3fa9",
  "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"
}

Attributes

Name	Type	Description
id	string	Unique identifier for the object.
amount	positive integer or zero	A positive integer representing how much to collect in the smallest currency unit (e.g., 100 cents to collect $1.00).
amount_refunded	positive integer or zero	Amount in cents refunded (can be less than the amount attribute on 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 currency of the crypto to be collected for this payment.
crypto_amount	string	The amount of crypto currency to be collected for this payment.
currency	currency	Three-letter ISO currency code, in uppercase. Must be a supported currency.
customer_id	string	ID of the customer this payment is for if one exists.
data_url	string	The URL which contains the data that the wallet apps need to complete the payment.
description	string	An arbitrary string attached to the object. Often useful for displaying to users.
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	ID of the order this payment is for if one exists.
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 `succeeded`, `pending`, or `cancelled`.

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

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,
  "data_url": "https://pay.crypto.com/sdk/payments/fa176d2e-8f58-419d-a531-e2c8e4dc3fa9",
  "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"
}

Arguments

Parameter	Required	Description
amount	required	A positive integer representing how much to collect in the smallest currency unit (e.g., 100 cents to charge $1.00).
currency	required	Three-letter ISO currency code, in uppercase. Must be a supported currency.
customer_id	optional	ID of the customer this payment is for if one exists.
description	optional	An arbitrary string attached to the object. Often useful for displaying to users.
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	ID of the order this payment is for if one exists.

Returns

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

Retrieve a payment

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 Crypto.com Pay will return the corresponding payment information. The same information is returned when creating or refunding the payment.

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,
  "data_url": "https://pay.crypto.com/sdk/payments/fa176d2e-8f58-419d-a531-e2c8e4dc3fa9",
  "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"
}

Arguments

Parameter	Required	Description
payment	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: \

Cancels 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,
  "data_url": "https://pay.crypto.com/sdk/payments/fa176d2e-8f58-419d-a531-e2c8e4dc3fa9",
  "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"
}

Arguments

Parameter	Required	Description
payment	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 \
  -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.

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,
  "data_url": "https://pay.crypto.com/sdk/payments/fa176d2e-8f58-419d-a531-e2c8e4dc3fa9",
  "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"
}]

Refunds

Endpoints

POST /api/refunds
GET /api/refunds/:id

Refund objects allow you to refund a payment that has previously been created but not yet refunded. Funds will be refunded to the Crypto.com App user who paid.

The refund object

The refund object

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

Attributes

Name	Type	Description
id	string	Unique identifier for the refund object.
status	string	The status of the refund is either `pending`, or `succeeded`.
payment_id	string	Unique identifier for the payment object.
currency	currency	Three-letter ISO currency code, in uppercase. Must be a supported currency.
amount	positive integer or zero	A positive integer representing how much to collect in the smallest currency unit
description	string	An arbitrary string attached to the object. Often useful for displaying to users.
reason	string	Reason for the refund. If set, 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.

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 some specific payment you made before.

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 or zero
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. Often useful for displaying to users.

Returns

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

Retrieve a refund

GET /refunds/:id

curl https://pay.crypto.com/api/refunds/4639e9bb-f85c-4f62-9d52-56dc0a8eb51b \
  -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 Crypto.com Pay will return the corresponding refund information.

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_at": 1555098162
}

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.

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.

Event Types

Event	Description
payment.created	New payment is created
payment.captured	Payment has been captured
payment.refund_requested	New refund is requested by merchant
payment.refund_transferred	Refund has been transferred to customer

There will be more events coming soon.

Webhook Endpoint

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

Webhook Signature

Crypto.com Pay can optionally sign the webhook events it 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 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 timestamp (as a string) The character . The actual JSON payload (i.e., the request’s body)

Step 3: Determine the expected signature

Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload string as the message.

Step 4: Compare signatures

Compare the signature(s) in the header to the expected signature. If a signature matches, 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.