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. 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.
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
- US Dollar Stable Coins (TUSD, USDC)
Minimum settlement amount is 20 USD.
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:
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 (Recommended)
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) {
// 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 thePayment ID
created in Step 3 into this container (attribute isdata-payment-id
).Then implement the
createPayment
function. This function will be invoked when the customer clicks on theCrypto.com Pay
button. Since you already have aPayment 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
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 theCrypto.com Pay Checkout
button. Theaction.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.
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.
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:
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 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. |
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 | 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",
"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. |
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. |
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": "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.