NAV Navbar
shell javascript

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

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

A Crypto.com App user can simply use the in-app scanner to scan the QR code and complete the transaction by paying their selected cryptocurrency. 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.

Payment Currencies

Crypto.com Pay Checkout currently accepts the following cryptocurrencies:

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

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.org Chain. Instead, the cashback incentives are granted to the customers as Crypto.com Pay Rewards when they choose to pay in CRO. Crypto.com Pay Rewards are always distributed back to Crypto.com App.

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

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

Refund

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

Payouts

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

Payout Currencies

Fiat Currencies

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.

Minimum settlement amount is 20 EUR. Bank account must be in SEPA countries. See list of SEPA countries here.

Cryptocurrencies

Minimum settlement amount is 0.003 BTC. Transfer is done via the Bitcoin Layer 1 network.

Minimum settlement amount is 20 of the respective currency. Transfer is done via the Ethereum Layer 1 network.

Integration Guides

Checkout Button SDK

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

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

alt text

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

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

Approach 1: Frontend and Backend Integration

Step 1: Register Crypto.com Pay Developer Access

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

Once you have access to the Crypto.com Pay Merchant Dashboard, You will be able to generate a secret key and publishable key pair. You should use the publishable key in the Crypto.com Pay 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=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. 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) {
        // Optional: add logic such as browser redirection or check data object content
      }
    }).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.

Then implement the onApprove function. You should add logic here to notify your server side which 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

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 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: 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 onApprove function. 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.

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.

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

It is a must for this flow to provide return_url when creating payment. The payment returned will contain a payment_url. When customers checkout on your site, you will have to redirect them to payment_url to finish the payment. After the payment become succeeded, the payment page will redirect customers back to return_url (or cancel_url if there is any issue).

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: 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, retrieve the payment and confirm whether payment status is succeeded. See all the statuses here.

Mobile Integration

You can follow the page redirection guide above to integrate Crypto.com Pay Checkout 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 become 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:

WooCommerce

Prestashop

Ecwid

Opencart

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",
  "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"
}

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 created in Crypto.com Pay Merchant Dashboard, if exists.
data_url string The URL which contains the data that the wallet apps need to complete the payment.
payment_url string The URL of the payment page which customers will navigate to in order to make the payment.
return_url string The URL for payment page to redirect 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. 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 Merchant provided order ID for this payment.
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",
  "data_url": "https://pay.crypto.com/sdk/payments/fa176d2e-8f58-419d-a531-e2c8e4dc3fa9",
  "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"
}

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.
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 Merchant provided order ID for this payment.
return_url optional The URL for payment page to redirect 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.

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",
  "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"
}

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: \

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",
  "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"
}

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 \
  -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",
  "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"
}]

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": "bbaa1ac7-a5ae-4a36-8f21-14d34ecb0b15",
  "currency": "USD",
  "amount": 5000,
  "debit_currency": "TUSD",
  "debit_amount": 0,
  "created": 1618283181,
  "reason": "Requested by customer",
  "description": "testing",
  "payment_id": "5e28e539-a7dd-4257-8b77-d2299d514959",
  "status": "prepared",
  "live_mode": true
}

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

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.

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

Webhook Signature

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

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

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

Verifying signatures

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

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

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

Step 1: Extract the timestamp and signatures from the header

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

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

Step 2: Prepare the signed_payload string

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

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

Step 3: Determine the expected signature

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

Step 4: Compare signatures

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

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

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

Troubleshooting

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

shell javascript