# Welcome Cryptopay offers the easiest and cheapest way to accept payments in bitcoin and other cryptocurrencies in Europe. We help innovative businesses around the world to incorporate cryptocurrency into their payment flows. We offer developer tools to accept cryptocurrency payments with an option of exchange rate hedging so that our customers are never exposed to cryptocurrency price volatility. # Introduction Cryptopay is a payment gateway and business wallet that allows merchants to automate the processes of accepting cryptocurrency payments and payouts from their customers, as well as making currency exchange transactions and receiving data on the transaction history and account balance statuses for reporting. # Environments In addition to the Production environment, Cryptopay also provides developers with a test environment - Sandbox, which mirrors the production environment and works with test networks (testnets) of all the cryptocurrencies that Cryptopay supports. Thus, developers can use the Sandbox environment to develop and test integration via [Cryptopay API.](https://reference.cryptopay.me/) | Environment | Base URL | | ----------- | -------------------------------------------------------------------------- | | Sandbox | | | Production | [https://business.cryptopay.me](< https://business.cryptopay.me >) | The Sandbox environment and the Production environment are independent and not connected to each other in any way. Here are the other base URLs utilized by Cryptopay, depending on the environment:

Utilized for	Production	Sandbox
Hosted page (for invoices and channels)	https://business-hosted.cryptopay.me/	https://hosted-business-sandbox.cryptopay.me/
Widget (online checkout)	https://business-widget.cryptopay.me/widget.js	https://widget-business-sandbox.cryptopay.me/widget.js
Payment links	https://business-pay.cryptopay.me/	https://pay-business-sandbox.cryptopay.me/
Hosted Item	https://business-catalog.cryptopay.me/	https://catalog-business-sandbox.cryptopay.me/
Web checkout (Legacy)	https://business-checkout.cryptopay.me/	https://checkout-business-sandbox.cryptopay.me/
Website / merchant account	https://cryptopay.me/business/	https://business-sandbox.cryptopay.me/business/

# Creating a Test Account Before proceeding with API integration, the developer will need to register and set up a test account. In order to do that, the following actions are required: * Register a test account by following this link: * You will receive an "Email address confirmation" letter asking you to confirm your email address – click on the blue "Confirm your email" button, and you will be redirected to the account password creation page. Create a password and log in to your account * Enable Two-factor authentication (2FA). This is a mandatory action. Once 2FA is enabled, you can use the security code 000000 to log in. * Contact your Integration or Account Manager at Cryptopay to activate your test account. You can also ask them to top up your test balances to be able to make test payments
# API Credentials Once your Cryptopay account is activated, you can generate the API Key and API Secret that are required to authenticate the API and indicate the Callback URL. {% hint style="info" %} Note that only **Root** and **Admin** user roles can access the Integration > API page. Here is [*a quick article*](https://help.cryptopay.me/en/articles/3415142-multiple-users-in-a-business-account) on how to manage users in your Cryptopay account. {% endhint %}

* **Callback URL** – in this field, you can specify the URL to which Cryptopay will send callbacks * **Callback Secret** – in this field, you can view the secret for [validating callbacks](https://developers.cryptopay.me/introduction/callbacks#security) and generate a new secret if necessary API keys - here you can generate the **API Key** and **API Secret** [to authenticate](https://developers.cryptopay.me/introduction/authentication) the Cryptopay API, specify the necessary permissions for the key to be created, and add IP addresses to the whitelist of that key.

The API secret should be stored on your side. Since it is only displayed once, you should write the API secret down or copy it into your application code immediately. If it is lost, you will need to delete the compromised API key and generate a new one. # API Basics ### Our API is REST-based on HTTPS * It works with standard HTTP verbs like `GET`, `POST` and `PATCH` * We use standard HTTP error responses to describe errors * All API requests MUST be made over SSL, including outgoing webhooks. Any non-secure requests return as `ssl_required`, and no redirects are performed * POST data should be encoded as standard `application/json` * All our responses are in JSON format # Responses Cryptopay API operates[ HTTP status codes](http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml) to indicate the status of user’s requests including both successful and unsuccessful responses. Responses will also include JSON-formatted data for further details: * 1xx (Informational): The request is received, continuing process * 2xx (Successful): The request is successfully received, understood, and accepted * 3xx (Redirection): Further action needs to be taken in order to complete the request * 4xx (Client Error): The request contains bad syntax or cannot be fulfilled * 5xx (Server Error): The server failed to fulfil an apparently valid request | Status code | Meaning | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200 OK` | Standard response for successful HTTP requests | | `201 Created` | The request has been fulfilled, resulting in the creation of a new resource | | `202 Accepted` | The request has been accepted for processing, but the processing has not been completed | | `204 No Content` | The server successfully processed the request and is not returning any content | | `304 Not Modified` | Indicates that the resource has not been modified since the version specified by the request headers If-Modified-Since or If-None-Match | | `400 Bad Request` | The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing) | | `401 Unauthorized` | Most likely you weren't able to construct and sign your API request correctly using HMAC | | `403 Forbidden` | You don't have required permissions to perform requested action on the resource. Check your API key whitelist | | `404 Not Found` | We don't have the resource you've requested | | `409 Conflict` | Most likely the `custom_id` value you are trying to use had been used before | | `422 Unprocessable Entity` | The request was well-formed but was unable to be followed due to semantic errors | | `429 API rate limit exceeded` | Amount API requests for api\_key exceeded 200 requests per minute | | `500 Internal Server Error` | We have a problem with our server | | `503 Service Unavailable` | We are temporarily offline for maintenance | # Date formats All timestamps are formatted using ISO 8601 format (RFC 3339). For those API calls that require a timestamp to be specified, it is necessary to use date and time in this format. Example: ``` 1994-11-15T08:12:31+00:00 ``` # Authentication API authentication is performed using the HMAC request signature sent in the `Authorization` header. ``` curl -X POST \ https://business-sandbox.cryptopay.me/api/invoices \ -H 'Authorization: HMAC DjlHuWlApznJ7vrhPBL0fA:N2eEvkJQ07EpFau90pL5xMpBO3g=' \ -H 'Content-Type: application/json' \ -H 'Date: Tue, 25 Sep 2018 17:41:40 GMT' \ -d '{"price_amount":"100","price_currency":"EUR","pay_currency":"BTC"}' ``` HMAC-SHA1 is an algorithm defined by [RFC 2104](https://www.ietf.org/rfc/rfc2104.txt) — Keyed-Hashing for Message Authentication. The algorithm takes as input two byte-strings, a key, and a message. # How it works The following describes steps, required to authenticate request signature using HMAC-SHA1: 1. You construct an API request (for API calls) 2. You calculate a keyed-hash message authentication code (HMAC-SHA1) signature using your API secret 3. You include both the API key and the signature in the `Authorization` header, and then call the API 4. The API uses your API key to look up your API secret 5. The API reconstructs the signature from the request data and the API secret with the same algorithm you used to calculate the signature you sent in the request 6. If the signature generated by Cryptopay matches the one you sent in the request, the request is considered authentic. If the comparison fails the request is discarded and Cryptopay returns `401` or `403` error responses: {% tabs %} {% tab title="401" %} ```javascript { "error": { "code": "unauthenticated", "message": "unauthenticated", "details": [] }, "meta": { "request_id": "932e4625b1735951f471cb7e7d3dab6e" } } ``` {% endtab %} {% tab title="403" %} ```javascript { "error": { "code": "unauthorized", "message": "unauthorized", "details": [] }, "meta": { "request_id": "932e4625b1735951f471cb7e7d3dab6e" } } ``` {% endtab %} {% endtabs %} # Signature The Signature is the RFC 2104 HMAC-SHA1, of selected elements from the request, and so the Signature part of the `Authorization` header will vary from request to request. | Component | Description | | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | HTTP method | `GET`, `POST`, `PUT`, `PATCH` | | MD5 hash sum of the string with JSON-serialized parameters | If there are no parameters in the request body (e.g. `GET`), you then need to place just an empty string `""` as there is nothing to hash. **Do not hash an empty string**. | | Content-Type | `application/json` | | Date | [HTTP-date](https://tools.ietf.org/html/rfc7231#section-7.1.1.2) format e.g. `Tue, 15 Nov 1994 08:12:31 GMT`. The time offset is 15 minutes | | Request URI | Everything that is after the base URL e.g. `/api/invoices` | Here is a piece of pseudo-code that demonstrates the `Authorization` header construction. `\n` means the Unicode code point `U+000A`, commonly called a newline: ``` StringToSign = HTTP-Verb + “\n” + Content-MD5 + “\n” + Content-Type + “\n” + Date + “\n” + Path Signature = Base64( HMAC-SHA1( Api.secret, UTF-8-Encoding-Of( StringToSign ) ) ); Authorization = "HMAC " + Api.key + “:” + Signature; ``` So this should look like the Authorization header below: ``` curl -X POST \ https://business-sandbox.cryptopay.me/api/invoices \ -H 'Authorization: HMAC DjlHuWlApznJ7vrhPBL0fA:N2eEvkJQ07EpFau90pL5xMpBO3g=' \ -H 'Content-Type: application/json' \ -H 'Date: Tue, 25 Sep 2018 17:41:40 GMT' \ -d '{"price_amount":"100","price_currency":"EUR","pay_currency":"BTC"}' ``` {% hint style="info" %} Make sure that the date used for signature is the same you put in the Date header {% endhint %} # Creating a signature. Code samples {% tabs %} {% tab title="Java" %} ```java import java.nio.charset.StandardCharsets; import java.security.InvalidKeyException; import java.security.MessageDigest; import java.security.NoSuchAlgorithmException; import java.security.NoSuchAlgorithmException; import java.util.Base64; import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; class Main { public static void main(String[] args) throws NoSuchAlgorithmException, InvalidKeyException { String secret = "Oe8TBDzg4tatdq2cL9ojeEj3U3oWSCSC5fqOHAqaKVg"; String method = "POST"; String body = "{\"amount\":\"100\"}"; String date = "2019-01-09T11:24:40+00:00"; String path = "/api/auth/test"; String contentType = "application/json"; // 5173e4d02d8a761679b0165b87d9ee5f String bodyMD5 = body.isEmpty() ? "" : md5hex(body); // POST\n5173e4d02d8a761679b0165b87d9ee5f\napplication/json\n2019-01-09T11:24:40+00:00\n/api/auth/test String stringToSign = String.join("\n", method, bodyMD5, contentType, date, path); // fVYzUdYqZO1ozBeP3KQHFp9/Kno= String signature = hmac(stringToSign, secret); System.out.println(signature); } private static String md5hex(String str) throws NoSuchAlgorithmException { MessageDigest md5 = MessageDigest.getInstance("MD5"); byte[] bytes = md5.digest(str.getBytes(StandardCharsets.UTF_8)); return hex(bytes); } private static String hmac(String str, String secret) throws InvalidKeyException, NoSuchAlgorithmException { SecretKeySpec secretKey = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA1"); Mac mac = Mac.getInstance("HmacSHA1"); mac.init(secretKey); byte[] result = mac.doFinal(str.getBytes(StandardCharsets.UTF_8)); String base64 = Base64.getEncoder().encodeToString(result); return base64; } private static String hex(byte[] bytes) { StringBuilder sb = new StringBuilder(); for (byte b : bytes) { sb.append(String.format("%02x", b)); } return sb.toString(); } } ``` {% endtab %} {% tab title="C#" %} ```csharp using System; using System.Collections.Generic; using System.IO; using System.Net; using System.Security.Cryptography; using System.Text; class Test { public static int Main() { Test test = new Test("https://business-sandbox.cryptopay.me", "your_API_key", "your_API_secret"); Console.WriteLine(test.CreateInvoice("{\"price_amount\":\"0.5\",\"price_currency\":\"ETH\",\"pay_currency\":\"ETH\"}")); Console.WriteLine(test.ListInvoices()); return 0; } private APIClient client; public Test(string baseURL, string key, string secret) { APIAuth auth = new APIAuth(key, secret); client = new APIClient(baseURL, auth); } public string CreateInvoice(string data) { return client.DoRequest("POST", DateTime.Now, "/api/invoices", data); } public string ListInvoices() { return client.DoRequest("GET", DateTime.Now, "/api/invoices"); } } class APIClient { private string baseURL; private APIAuth auth; public APIClient(string url, APIAuth apiAuth) { baseURL = url; auth = apiAuth; } public string DoRequest(string verb, DateTime date, string path, string data = "", string contentType = "application/json", List> Headers = null) { ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12; HttpWebRequest request = (HttpWebRequest)WebRequest.Create(baseURL + path); HttpWebResponse response; StreamWriter sw; StreamReader sr; string dateStr; string responseData; request.Method = verb; request.ContentType = contentType; request.ContentLength = data.Length; request.Date = date; dateStr = date.ToUniversalTime().ToString("r"); request.Headers.Add("Authorization", auth.GenerateAuthorizationHeader(verb, data, contentType, dateStr, path)); if (verb != "GET") { sw = new StreamWriter(request.GetRequestStream()); sw.Write(data); sw.Close(); } response = (HttpWebResponse)request.GetResponse(); sr = new StreamReader(response.GetResponseStream()); responseData = sr.ReadToEnd(); return (responseData); } } class APIAuth { private string key; private string secret; public APIAuth(string apikey, string apisecret) { key = apikey; secret = apisecret; } public string GenerateAuthorizationHeader(string httpVerb, string jsonBodyStr, string httpContentType, string dateStr, string relativeUrl) { string signature = GenerateSigniture(httpVerb, jsonBodyStr, httpContentType, dateStr, relativeUrl); return $"HMAC {key}:{signature}"; } public string GenerateSigniture(string httpVerb, string jsonBodyStr, string httpContentType, string dateStr, string relativeUrl) { string jsonBodyHash = String.IsNullOrEmpty(jsonBodyStr) ? "" : GetMD5Hash(jsonBodyStr); string signitureData = string.Join("\n", httpVerb, jsonBodyHash, httpContentType, dateStr, relativeUrl); byte[] apiSecretBytes = Encoding.UTF8.GetBytes(secret); byte[] signitureBytes = Encoding.UTF8.GetBytes(signitureData); var hmacsha1 = new HMACSHA1(apiSecretBytes, false); byte[] resultBytes = hmacsha1.ComputeHash(signitureBytes); return Convert.ToBase64String(resultBytes); } private string GetMD5Hash(string text) { StringBuilder returnvalue = new StringBuilder(); MD5CryptoServiceProvider cryptoSP = new MD5CryptoServiceProvider(); byte[] HashBytes = Encoding.UTF8.GetBytes(text); HashBytes = cryptoSP.ComputeHash(HashBytes); foreach(byte bte in HashBytes) returnvalue.Append(bte.ToString("x2").ToLower()); return returnvalue.ToString(); } } ``` {% endtab %} {% tab title="VB.NET" %} ```java Imports System Imports System.Collections.Generic Imports System.IO Imports System.Net Imports System.Security.Cryptography Imports System.Text Class Test Public Shared Function Main() As Integer Dim auth As APIAuth = New APIAuth("key", "secret") Dim client As APIClient = New APIClient("https://business-sandbox.cryptopay.me", auth) Dim path As String = "/api/invoices" Dim data As String = "{""price_amount"":""0.5"",""price_currency"":""ETH"",""pay_currency"":""ETH""}" Dim response As String = client.DoRequest(DateTime.Now, path, data) Console.WriteLine(response) Return 0 End Function End Class Class APIClient Private baseURL As String Private auth As APIAuth Public Sub New(ByVal url As String, ByVal apiAuth As APIAuth) baseURL = url auth = apiAuth End Sub Public Function DoRequest(ByVal date As DateTime, ByVal path As String, ByVal Optional data As String = "", ByVal Optional contentType As String = "application/json", ByVal Optional Headers As List(Of KeyValuePair(Of String, String)) = Nothing, ByVal Optional verb As String = "POST") As String ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12 Dim request As HttpWebRequest = CType(WebRequest.Create(baseURL & path), HttpWebRequest) Dim response As HttpWebResponse Dim sw As StreamWriter Dim sr As StreamReader Dim dateStr As String Dim responseData As String request.Method = verb request.ContentType = contentType request.ContentLength = data.Length request.Date = date dateStr = date.ToUniversalTime().ToString("r") request.Headers.Add("Authorization", auth.GenerateAuthorizationHeader(verb, data, contentType, dateStr, path)) sw = New StreamWriter(request.GetRequestStream()) sw.Write(data) sw.Close() response = CType(request.GetResponse(), HttpWebResponse) sr = New StreamReader(response.GetResponseStream()) responseData = sr.ReadToEnd() Return (responseData) End Function End Class Class APIAuth Private key As String Private secret As String Public Sub New(ByVal apikey As String, ByVal apisecret As String) key = apikey secret = apisecret End Sub Public Function GenerateAuthorizationHeader(ByVal httpVerb As String, ByVal jsonBodyStr As String, ByVal httpContentType As String, ByVal dateStr As String, ByVal relativeUrl As String) As String Dim signature As String = GenerateSigniture(httpVerb, jsonBodyStr, httpContentType, dateStr, relativeUrl) Return $"HMAC {key}:{signature}" End Function Public Function GenerateSigniture(ByVal httpVerb As String, ByVal jsonBodyStr As String, ByVal httpContentType As String, ByVal dateStr As String, ByVal relativeUrl As String) As String Dim jsonBodyHash As String = GetMD5Hash(jsonBodyStr) Dim signitureData As String = String.Join(vbLf, httpVerb, jsonBodyHash, httpContentType, dateStr, relativeUrl) Dim apiSecretBytes As Byte() = Encoding.UTF8.GetBytes(secret) Dim signitureBytes As Byte() = Encoding.UTF8.GetBytes(signitureData) Dim hmacsha1 = New HMACSHA1(apiSecretBytes, False) Dim resultBytes As Byte() = hmacsha1.ComputeHash(signitureBytes) Return Convert.ToBase64String(resultBytes) End Function Private Function GetMD5Hash(ByVal text As String) As String Dim returnvalue As StringBuilder = New StringBuilder() Dim cryptoSP As MD5CryptoServiceProvider = New MD5CryptoServiceProvider() Dim HashBytes As Byte() = Encoding.UTF8.GetBytes(text) HashBytes = cryptoSP.ComputeHash(HashBytes) For Each bte As Byte In HashBytes returnvalue.Append(bte.ToString("x2").ToLower()) Next Return returnvalue.ToString() End Function End Class ``` {% endtab %} {% tab title="PHP" %} ```php apiKey = $apiKey; $this->apiSecret= $apiSecret; } public function buildRequestHeaders($method, $path, $body, $headers) { if ($body) { $bodyHash = md5($body); } else { $bodyHash = ''; } $date = $headers['Date']; $contentType = $headers['Content-Type']; $sigString = implode("\n", [$method, $bodyHash, $contentType, $date, $path]); $signature = base64_encode(hash_hmac('sha1', $sigString, $this->apiSecret, true)); return [ 'Authorization' => 'HMAC '.$this->apiKey.':'.$signature ]; } } ``` {% endtab %} {% tab title="Ruby" %} ```ruby api_key = 'DjlHuWlApznJ7vrhPBL0fA' api_secret = '3pPl6TbsoRlz0FLpKM6r-UG788g4-Fk5d1v1gKdXAA8' string_to_signature = [ 'POST', 'ba3c4838768171e3a221a9d619f5440c', 'application/json', 'Tue, 25 Sep 2018 17:41:40 GMT', '/api/invoices' ].join("\n") digest = OpenSSL::Digest.new('sha1') signature = OpenSSL::HMAC.digest(digest, api_secret, string_to_signature) encoded_signature = Base64.strict_encode64(signature) ``` {% endtab %} {% tab title="JavaScript" %} {% code fullWidth="true" %} ```javascript payload_MD5 = CryptoJS.MD5(request.data).toString(); date = new Date(Date.now()).toUTCString(); string_to_sign = "POST" + "\n" + payload_MD5 + "\n" + "application/json" + "\n" + date + "\n" + "/api/channels" hmac = CryptoJS.HmacSHA1(string_to_sign, "MoJj8czcibe0kMBUc69O5AhlEI7oafGkLBjOgNaekLA"); signature = hmac.toString(CryptoJS.enc.Base64); ``` {% endcode %} {% endtab %} {% tab title="Python" %} ```python import requests import json import hmac import hashlib import base64 from wsgiref.handlers import format_date_time from datetime import datetime from time import mktime ######################################### ### https://reference.cryptopay.me/ ### ######################################### # Api keys api_key = "your_API_key" api_secret = "your_API_secret" # Content type content_type = "application/json" # Date payment_date = format_date_time(mktime(datetime.now().timetuple())) # [Cryptopayme] Create payment # https://reference.cryptopay.me/#tag/Invoices/operation/invoices.create def create_invoice_payment_cryptopayme(price_amount, price_currency, pay_currency, custom_id, name, description): if price_amount and price_currency and pay_currency: payment_host = "https://business-sandbox.cryptopay.me" payment_path = "/api/invoices" payment_url = payment_host + payment_path payment_data = { "price_amount": str(price_amount), "price_currency": str(price_currency), "pay_currency": str(pay_currency), } body = json.dumps(payment_data) bodyhash = hashlib.md5(str.encode(body)).hexdigest() sigstring = "POST\n" sigstring += bodyhash + "\n" sigstring += content_type + "\n" sigstring += payment_date + "\n" sigstring += payment_path digest = hmac.new(str.encode(api_secret), str.encode(sigstring), hashlib.sha1) signature = base64.b64encode(digest.digest()) authorization = "HMAC " + api_key + ":" + signature.decode('utf-8') headers = { "Authorization": authorization, "Content-Type": content_type, "Date": payment_date, } # Log (Request headers) f = open("request-log.json", "w") f.write(json.dumps(headers)) f.write("\n") f.write(body) f.close() # Request post response = requests.post(payment_url, headers=headers, data=body) # Log (Response) # Log (Request headers) f = open("response.json", "w") f.write(response.text) f.close() if response.status_code == 201: response_data = json.loads(response.text) payment_redirect_url = response_data["data"]["hosted_page_url"] return payment_redirect_url else: return None else: return None print(create_invoice_payment_cryptopayme("10", "EUR", "XRP", "", "", "")) ``` {% endtab %} {% endtabs %} # Callbacks It is a good idea to create an IPN listener page on your website and then specify the URL of the listener page in a "Integration → API" section in your Cryptopay account. It is also important to note that you should use only `https` URL. Cryptopay then sends a secure POST request containing payment details of all transaction-related events to the URL. {% hint style="danger" %} Handling callbacks correctly is crucial to make sure your integration’s business logic works as expected. It is highly recommended to validate payment statuses and callbacks before acting on it inside your system. {% endhint %} The IPN listener page contains a custom script or a program that gets messages, validates them with Cryptopay, and then passes them to various backend applications for processing. Take a look at examples of callbacks: \ — for an invoice — [here](https://developers.cryptopay.me/guides/invoices/callbacks).\ — for a channel — [here](https://developers.cryptopay.me/guides/channels/callbacks).\ — for a coin withdrawal — [here](https://developers.cryptopay.me/guides/payouts/callbacks). ### Acknowledge events immediately If your callbacks script performs complex logic, or makes network calls, it’s possible that the script would time out before Cryptopay sees its complete execution. Ideally, your callback handler code (notification of an event by returning a `200` status code) is separate from any other logic you do for that event. ### Handle duplicate events Callback endpoints might occasionally receive the same event more than once. We advise you to guard against duplicated event receipts. One way of doing this is logging the events you’ve processed, and then not processing the logged ones. ### Retry logic Cryptopay IPN server expects to get a `200` status code from you within 10 seconds. If the response code is different from `200` or a deadline is exceeded, we deliver your callbacks for up to one and a half days with an exponential backoff: `30 + num ^ 4 + num` seconds where `num` is 0 to 19 retry ``` 0d 00h 00m 30s 0d 00h 00m 32s 0d 00h 00m 48s 0d 00h 01m 54s 0d 00h 04m 50s 0d 00h 11m 00s 0d 00h 22m 12s 0d 00h 40m 38s 0d 01h 08m 54s 0d 01h 50m 00s 0d 02h 47m 20s 0d 04h 04m 42s 0d 05h 46m 18s 0d 07h 56m 44s 0d 10h 41m 00s 0d 14h 04m 30s 0d 18h 13m 02s 0d 23h 12m 48s 1d 05h 10m 24s 1d 12h 12m 50s ``` ### Security Every callback request contains a `X-Cryptopay-Signature` header: ``` "X-Cryptopay-Signature": "7c021857107203da4af1d24007bb0f752e2f04478e5e5bff83719101f2349b54" ``` This header contains the hex encoded SHA256 HMAC signature of the callback request body string, computed using your callback Secret as the key. 1. You receive a callback 2. You use SHA256 for hashing its body string with a callback secret 3. You compare `X-Cryptopay-Signature` value to the hash you've got after hashing the callback body string + callback secret {% tabs %} {% tab title="Ruby" %} ```ruby class CryptopayCallbackVerifier def initialize(secret) @secret = secret end def verify(body, signature) expected_signature = OpenSSL::HMAC.hexdigest('SHA256', @secret, body) OpenSSL.secure_compare(signature, expected_signature) end end secret = 'hzeRDX54BYleXGwGm2YEWR4Ony1_ZU2lSTpAuxhW1gQ' verifier = CryptopayCallbackVerifier.new(secret) # Raw callback body body = '{"type":"Invoice","event":"status_changed","data":{"id":"ff48eeba-ab18-4088-96bc-4be10a82b994","status":"completed","status_context":null,"address":"rs9pE6CnNLE8YiTgTwbAk1AkFyS3opsm7K?dt=701","price_amount":"1.0","price_currency":"EUR","pay_amount":"3.113326","pay_currency":"XRP","paid_amount":"3.113326","exchange":{"pair":"XRPEUR","rate":"0.3212"},"transactions":[{"txid":"3EA591FED2F1F61263CB66AAC6BCF520B0714A08F2481D56DE267F31E0C782B9","risk":null}],"name":null,"description":null,"metadata":null,"custom_id":null,"success_redirect_url":null,"created_at":"2019-04-09T15:22:09+00:00","expires_at":"2019-04-09T15:32:09+00:00"}}' # Value of X-Cryptopay-Signature header signature = '7c021857107203da4af1d24007bb0f752e2f04478e5e5bff83719101f2349b54' verifier.verify(body, signature) # => true ``` {% endtab %} {% endtabs %} {% hint style="info" %} Every new callback request will have a new value of the `X-Cryptopay-Signature` header. Make sure you are comparing the hash to the right header. {% endhint %} A callback secret is available in the "Integration → API" section in your Cryptopay account. ### Callback IPs We send all our callbacks from these IP: * Production - 63.33.129.150 * Sandbox - 3.249.128.101 You can use these IPs as a whitelist for receiving callbacks. Callbacks reference can be found in relevant sections of the API reference: {% embed url="" %} # API Client Libraries * [PHP](https://github.com/cryptopay-dev/cryptopay-php) * [Ruby](https://github.com/cryptopay-dev/cryptopay-ruby) * [Java](https://github.com/cryptopay-dev/cryptopay-java) * [JavaScript](https://github.com/cryptopay-dev/cryptopay-node) # API Reference API Reference can be found here: {% embed url="" %} # Cryptocurrency Payments Popular payment methods such as bank and credit card payments are based on the fact that customers specify their data and their card details in payment forms. The information collected is then used to extract payments directly from the user. Cryptocurrency payments work differently. Customers use their wallets to send payments directly to the merchant. Customers specify the destination address and the amount of the cryptocurrency before sending the funds. In this sense, cryptocurrency payments are push payments. Cryptopay payment gateway offers two different tools for accepting cryptocurrency payments - Invoices and Channels.
# Currencies To keep the list of coins in your systems up to date use the [`GET /api/coins`](https://reference.cryptopay.me/#tag/Coins/operation/coins.list) endpoint. The endpoint provides the following information: * Array of available coins and all supported networks * Currency - currency ticker * Name - name of currency, network or destination tag * Precision - number of decimal places supported by coin * Destination tag - the presence of an additional `destination_tag` field for the coin. If `destination_tag` is not `null`, then there is an additional field for the coin and it must be shown to the user when the user is paying, as well as give an opportunity to the user to specify it, on par with the wallet address, when withdrawing funds. Additional parameter `required` specifies the obligation to send `destination_tag` when requesting a coin withdrawal: * `required: true` - you cannot create a withdrawal without specifying `destination_tag`. If the user doesn't specify it, add `dt=0` to the request. * `required: false` - you can create a withdrawal without `destination_tag`. If the user didn't specify it - don't add `dt` to the request. {% hint style="info" %} Destination tag is similar to a reference number for bank transfers. It helps to identify transactions when a single address is used by multiple users. {% endhint %} * Logo url - link to logo of the coin * Invoices, channels, coin withdrawals - availability for use in invoices, channels and coin withdrawals. Switches to false during maintenance on our side. # Supported Currencies The list of supported cryptocurrencies.

Currency Code	Currency Name	Precision	Supported Networks
BTC	Bitcoin	8	bitcoin, bnb_smart_chain
LTC	Litecoin	8	litecoin, bnb_smart_chain
ETH	Ethereum	8	ethereum, bnb_smart_chain
XRP	XRP	6	ripple, bnb_smart_chain
XLM	Stellar Lumens	7	stellar, bnb_smart_chain
BCH	Bitcoin Cash	8	bitcoin_cash, bnb_smart_chain
ADA	Cardano	6	cardano, bnb_smart_chain
SOL	Solana	9	solana, bnb_smart_chain
SHIB	Shiba Inu	0	ethereum, bnb_smart_chain
TRX	TRON	6	tron, bnb_smart_chain
DOGE	Dogecoin	8	dogecoin, bnb_smart_chain
BNB	BNB	8	bnb_smart_chain
USDT	Tether	6	ethereum, tron, bnb_smart_chain, solana, polygon, ton
USDC	USD Coin	6	ethereum, bnb_smart_chain, solana
DAI	Dai	8	ethereum, bnb_smart_chain
POL	POL	8	polygon
ARB	Arbitrum	8	arbitrum
GRAM (TON)	Toncoin	8	ton
IMX	ImmutableX	8	ethereum
FTN	Fasttoken	8	bahamut

The list of supported fiat currencies. | Currency Code | Currency Name | Precision | | ------------- | ----------------------- | --------- | | EUR | Euro | 2 | | USD | United States dollar | 2 | | GBP | Pound sterling | 2 | | CAD | Canadian dollar | 2 | | AUD | Australian dollar | 2 | | NZD | New Zealand dollar | 2 | | HKD | Hong Kong dollar | 2 | | JPY | Japanese yen | 0 | | KRW | South Korean won | 0 | | CLP | Chilean peso | 0 | | CNY | Renminbi (Chinese) yuan | 2 | | TRY | Turkish lira | 2 | | TWD | New Taiwan dollar | 2 | | MXN | Mexican peso | 2 | | BRL | Brazilian real | 2 | | COP | Colombian peso | 2 | | THB | Thai baht | 2 | | NOK | Norwegian krone | 2 | | SEK | Swedish krona | 2 | | PLN | Polish złoty | 2 | | HUF | Hungarian forint | 2 | | VND | Vietnamese dong | 0 | | IDR | Indonesian rupiah | 2 | | UAH | Ukrainian hryvnia | 2 | | KZT | Kazakh tenge | 2 | | CHF | Swiss franc | 2 | | MYR | Malaysian Ringgit | 2 | | SGD | Singapore Dollar | 2 | | PEN | Peruvian Sol | 2 | | CZK | Czech Koruna | 2 | | DKK | Danish Krone | 2 | | ZAR | South African Rand | 2 | | INR | Indian Rupee | 2 | | PHP | Philippine peso | 2 | | UZS | Uzbekistani sum | 2 | # Currency Icons Click on the link below to download Bitcoin, Bitcoin Cash, Ether, XRP and Litecoin icons in SVG, PNG and JPG formats. {% file src="/files/-LucMt624M0fT9CkW9rf" %} BTC, BCH, ETH, XRP LTC icons {% endfile %} # Confirmations An incoming transaction will not be processed until it gets a required number of confirmations. The number of required confirmations depends on a transaction amount.

Chain	Required confirmations
Bitcoin	1 confirmation if transaction amount is 1 BTC or lower 3 if amount is 1 - 10 BTC 6 if amount is more than 10 BTC
Bitcoin Cash	1 if transaction amount is 1 BCH or lower 3 if amount is 1 - 10 BCH 6 if amount is more than 10 BCH
Litecoin	1 if transaction amount is 1 LTC or lower 3 if amount is 1 - 2 LTC 6 if amount is more than 2 LTC
Dogecoin	1 if the transaction amount is 1000 DOGE or lower 3 if amount is 1000 DOGE - 10000 DOGE 6 if the amount is more than 10000 DOGE
ETH	2 if the transaction amount is 0,3 ETH or lower 3 if amount is 0,3 ETH - 3 ETH 6 if the amount is more than 3 ETH
USDT in the Ethereum network (ERC 20)	3 if the transaction amount is 1000 USDT or lower 5 if amount is 1000 USDT - 5000 USDT 6 if the amount is more than 5000 USDT
All other coins in the Ethereum network (ERC 20)	12
BNB and all coins in the BNB Smart Chain (BEP20)	15
TRX and all coins in the Tron network (TRC20)	1
Cardano	30
Ripple	1
Stellar	1
Solana	1
Polygon	127
TON	1
Arbitrum	30
Bahamut	3

# Tools for accepting payments Cryptopay Business offers several solutions to accept payments, which allow you to flexibly integrate them into the purchase process. ### **Channels** They are used as permanent cryptocurrency addresses dedicated to each of your customers. All the incoming payments will be automatically converted into the specified currency and credited to the payer's balance. The process of accepting channel payments includes: 1. the payer selects a payment in cryptocurrency as a payment method and selects a type of cryptocurrency; 2. the wallet number for the payment is shown; 3. it's possible to send any amount to the wallet; the entire amount sent will be converted according to the rate at the moment when it's received and credited to the balance; 4. the same channel address can be used multiple times with any time interval between them; all payments will be credited to the user's balance. Please note that channels don’t support the ability to indicate a fixed amount in fiat, which the user will receive after a successful payment. ### **Invoices** Invoices are used to credit a fixed amount in fiat currency to the balance, or to make a purchase at a price determined at the time of a payment. The process of accepting invoice payments includes: 1. the payer indicates an amount in a fiat currency, which is necessary to credit to the balance (or adds the desired goods to the cart); 2. the payer selects a payment in crypto as a payment method and selects a type of cryptocurrency; 3. we freeze the rate for the client for the 10 minutes, during which the customer can make a payment in order to receive an indicated amount to the balance; 4. the wallet number and the amount are shown for a payment, as well as the time during which the transaction needs to be made; 5. upon successful completion of the payment, the user receives the indicated amount to the balance. For each new payment, a new invoice is generated. Rules for invoices' refunds which are paid with an error are [configured separately](https://developers.cryptopay.me/guides/invoices/how-to-handle-unresolved-invoices). ### Ready-made payment solutions based on invoices On the basis of invoices, several ready-made solutions have been implemented, which allow you to make quick integration, or use them manually without integration. #### **Payment links** A payment link, to which you can transmit the payment parameters. By clicking the link, the user leaves the site and gets to the checkout page, where he can complete the payment. Payment links are flexibly integrated into the sales process and allow you to receive information about incoming payments automatically. [Learn more about payment links](https://developers.cryptopay.me/guides/invoices/payment-links). #### Online checkout The ready-made solution allows you to integrate the payment process into the site and automatically receive information about incoming payments. [More about the online checkout](https://developers.cryptopay.me/guides/invoices/payment-widget). #### Web checkout (POS) It generates a payment link. The payers can specify the amount in fiat currency by themselves, then select the cryptocurrency for a payment and pay. The existence and status of the transaction is monitored manually. It can be used for accepting offline payments. [Learn more about web checkout (POS)](https://help.cryptopay.me/en/articles/6608883-web-checkout). # Prebuilt integrations # E-commerce payment plugins E-commerce plugins allow you to quickly set up cryptocurrency payments in popular e**-**commerce platforms.

Name	Link
OpenCart	https://www.opencart.com/index.php?route=marketplace/extension/info&extension_id=43907
WooCommerce
Adobe Commerce (Magento)
VirtueMart
PrestaShop

### Setting up the plugin To start using the plugin you need to: 1. Sign up and get verified on [Cryptopay for Business](https://business.cryptopay.me/). 2. Install the plugin. 3. Fill in the widget key and the callback secret fields in the plugin settings: * The Widget key can be found in your Cryptopay Business account on the Integration page → Online checkout. * The callback secret can also be found in your Cryptopay for Business account on the Integration page → API. 4. In your account settings, fill in the Callback URL field using the address from the CMS plugin settings: * The callback URL can be found in the CMS plugin settings. * The callback URL has to be filled in the Cryptopay for Business account on the Integration page → API. 5. Define the rules for handling [unresolved invoices](https://help.cryptopay.me/en/articles/3415145-how-to-handle-unresolved-invoices). 6. Activate the plugin in the CMS settings. ### **Description of plugin settings** * `Environment` is a choice between two environments: Sandbox and Production. The Sandbox environment allows you to test the plugin's operation before running it in Production. Please click here to find out more information. * `Widget key` is a key for linking plugins to Cryptopay for Business projects. * `Callback URL` is the URL where Cryptopay for Business will send the payment status callbacks. * `Callback secret` is a signature required to verify validity of the callbacks. * `Theme` is a theme of the payment page, which will be redirected to from your website. * `Show Qr code` - if this option is disabled, the Qr code will be hidden behind the button ( for mobile devices). # Payment and software providers Cryptopay Business has partnered and integrated with major software providers. These companies supply businesses operating in specific sectors with a payment module that integrates various types of payment solutions, such as card payments, online wallets and cryptocurrency payments. Cryptopay Business is integrated with such platforms and provides a cryptocurrency payment service for their payment modules. We have partnered with: * Payment IQ () * Premier Cashier () * Money Matrix ([https://moneymatrix.com/]()) * Betconstruct () * Praxis Cashier () * Corefy ([https://corefy.com/]()) If your product is already built on one of our supported payment providers, implementing Cryptopay Business will be easier and faster than direct API integration. ### **How to incorporate Cryptopay for Business through payment providers?** 1. Sign up and get verified on Cryptopay for Business. 2. Choose the payment acceptance type ([Invoices ](https://developers.cryptopay.me/guides/invoices)or [Channels](https://developers.cryptopay.me/guides/channels)). Our Support team or Integration manager will help you to make a decision. 3. Contact your payment provider and advise them of your payment method choice, and receive their instructions on how to set up Cryptopay on their side. 4. Generate a new API key and submit it to the payment processor. You can generate a new API key on the Integration page -> API. 5. In the Cryptopay Business integration page, please fill in the Callback URL field. * Callback URL has to be obtained from the payment provider * Callback URL has to be filled in the Cryptopay for Business account on the Integration page → API. 6. In case you choose to accept payments via invoices, please don't forget to define the rules for handling [unresolved invoices.](https://help.cryptopay.me/en/articles/3415145-how-to-handle-unresolved-invoices) We recommend you to make an initial integration on [the sandbox environment](/guides/envs) to test the functionality before opening a prod account.
# Channels A [channel](https://reference.cryptopay.me/#tag/Channels) is a static cryptocurrency address that may be assigned to each one of your customers. They can send cryptocurrency to these addresses and it will be automatically exchanged into Euro or other fiat currency of your choice. Primarily the premise of a channel is the customer is shown the information in the Cashier the first time, and they can then re-use it which is highly convenient - they can deposit funds without going to the Cashier, or even logging in. The trade-off in this approach is that customers receive the exchange rate at the moment when the transactions are confirmed on the network, not when they first send them. The exchange is made at the moment when we receive the funds. Therefore, customers can receive a little more/ a little less. The upside of channels for you is, there is minimal customer support required. E.g. for invoices, if customers send funds to a previously used address, you will have to manually reconcile and communicate with the customer. One key thing to make sure of: once a channel has been [created](https://reference.cryptopay.me/#tag/Channels/operation/channels.create) for a customer (when they've made their first deposit request through the Cashier), it's important that if they go back to the Cashier and initiate another deposit, that you display the same channel details to them and do not create a new channel - this is the best user experience. As cryptocurrency payments are made over a separate network, when creating a channel, we generate a unique payment address for each cryptocurrency so we can match customers to their payments. When a customer makes a cryptocurrency payment, the transaction is then broadcast to the cryptocurrency network for validation/confirmation. It means that if you want to give the customer an opportunity to make payments not only in Bitcoin, but also in other cryptocurrencies, then in addition to the BTC channel you will need to create more channels for such customers. Once the channel is created, we start monitoring the unique address of the channel to identify any incoming transactions. When we locate an incoming transaction at the channel address, we create a Channel Payment and process it. When Channel is created, there's no way to archive it on our side or switch it off. If the Channel is no longer needed, simply stop displaying it on your end.
# Channel payment Channel Payment is the actual payment made by the customer. The transaction of the `ChannelPayment` type is automatically created in your account whenever the user sends the cryptocurrency to the channel address. Each channel payment has statuses - every time channel payment changes its status, Cryptopay sends [callbacks](https://developers.cryptopay.me/guides/api-basics/callbacks) to the Callback URL. Every time the transaction is found at the channel address, we create a channel payment with `pending` status. This means that the payment has just been detected, but has not yet been validated by the network. When the transaction is completely validated and confirmed by the network, the payment status changes to `completed`.
# Payment statuses Each Channel Payment is associated with its parent Channel. Channel Payments have several `status` options and we send [callbacks](/guides/api-basics/callbacks) on every status change. | **status** | **status\_context** | **Description** | | ----------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `pending` | `null` | A channel payment has been created. It means that a customer has just broadcast their transaction on the network | | `completed` | `null` | The transaction has been confirmed on the network and the payment amount has been added to your account balance | | `on_hold` | `illicit_resource` | The received cryptocurrency transaction has been evaluated as High-Risk, therefore the payment transaction has been put on hold | | `on_hold` | `channel_disabled` | A parent Channel has been disabled, therefore the payment transaction has been put on hold | | `refunded` | `null` | The funds have been returned to the sender | | `cancelled` | `null` | The transaction hasn't been confirmed on the network within 14 days | You can see that there are 3 other statuses besides `pending` and `completed`. For example, the `cancelled` status is assigned to a payment if the transaction has not been confirmed on the blockchain within 14 days since the customer sent it to the channel address. This may occur when the user has made a double spend of funds. The `on_hold` status with the `illicit_resource` context is assigned to a payment when the payment has received a high risk level. In case you get a High-Risk payment it is required you contact us at . Our Transaction Monitoring team will review this transaction shortly to make a decision on whether we will be able to reduce the risk level and process this payment and add the funds to your account balance, or we will have to send the funds back to the sender. Please refer to the [Risks](/guides/risks) section to get more details on what High-Risk transactions are and why we take it very seriously. Once the transaction has been sent back, the payment will change its status to `refunded`. If the payment has not been returned to the sender but has been credited to the merchant balance, the payment changes its status to `completed`. ## Channel payment statuses diagram

All the steps from creation of the channel to the moment the payment is credited to the balance can also be viewed [here](/guides/channels/payment-sequence). # Channel payment sequence Channel payment sequence.

# Create a Channel First of all, let’s [create a channel](https://reference.cryptopay.me/#tag/Channels/operation/channels.create) for our customer: ``` curl -X POST \ https://business-sandbox.cryptopay.me/api/channels \ -H 'Authorization: HMAC ***' \ -H 'Content-Type: application/json' \ -H 'Date: Tue, 19 Mar 2019 10:11:40 GMT' \ -d '{"pay_currency":"BTC", "network":"bitcoin", "receiver_currency":"EUR", "name":"channel name", "custom_id":"631044494"}' ``` Let’s go over the parameters we used in the request above: * `pay_currency` - is a cryptocurrency in which the customer will make a payment (in our case it is `BTC`) * `network` - the blockchain in which the address is going to be created. The list of available networks can be found [here](https://developers.cryptopay.me/guides/currencies/currencies). * `receiver_currency` - the currency to which incoming cryptocurrency transactions will be converted and in which the merchant will be credited to the balance account (in our case it is `EUR`) * `name` - any channel name * `custom_id` - we recommend indicating a certain reference by which you associate your customer with the created channel. It is important to note that all channel payments of this channel will be inherited by the parent channel - for example, `631044494` You will receive the channel’s address and a link to its [hosted page](/guides/channels/channel-hosted-page), which can be integrated into your website: ```javascript { "customer_id": "e7bb04fb-7f33-4729-819e-05a92761b492", "id": "50eb5775-f77e-4c64-870b-dc93624b5967", "name": "channel name", "description": "channel description", "receiver_currency": "EUR", "pay_currency": "BTC", "address": "2N9uVK2MDFNgBVqPnvCTV66Dinx3cp5J7S4", "network": "bitcoin", "project_id": "25632c89-7f40-4693-8ed0-99bf5f79d3a6", "custom_id": "631044494", "uri": "bitcoin:2N9uVK2MDFNgBVqPnvCTV66Dinx3cp5J7S4", "hosted_page_url": "https://business-hosted.cryptopay.me/channels/50eb5775-f77e-4c64-870b-dc93624b5967" } ``` To create a channel payment, we need to send a BTC transaction to the Bitcoin address of our newly created channel `2N9uVK2MDFNgBVqPnvCTV66Dinx3cp5J7S4`. In order to send the transaction, please login to your test account and press the "Send" button, which is located on your Bitcoin account:

In the pop-up window, enter the address and amount of the transaction, and complete the process. {% hint style="info" %} You can also automate the process of sending transactions using [this endpoint](https://reference.cryptopay.me/#tag/Coin-withdrawals/operation/coin-withdrawals.create) so that you do not have to create payments manually. {% endhint %} Once the payment is sent, we will create a Channel Payment transaction in your account and send the [callbacks](/guides/api-basics/callbacks) to the Callback URL. We also recommend you using [this endpoint](https://reference.cryptopay.me/#tag/Channels/operation/channels.retrieve-payment) to check the channel payment status before depositing funds to your customer's balance, as delivery of the callbacks is not guaranteed. Below is an example of a callback for the final status `completed`: ```javascript { "type": "ChannelPayment", "event": "completed", "data": { "id": "284d4b79-fea6-46ce-bc2f-0f9cbed6367e", "txid": "09723bf75253f3d2bf2f150fd8b5da5bc3026b95f1fe50b1f5f76f43d67a2e30", "address": "2N9uVK2MDFNgBVqPnvCTV66Dinx3cp5J7S4", "network": "bitcoin", "paid_amount": "0.02", "paid_currency": "BTC", "received_amount": "97.26", "received_currency": "EUR", "fee": "0.99", "fee_currency": "EUR", "exchange": { "pair": "BTCEUR", "rate": "4912.8021" }, "status": "completed", "channel_id": "50eb5775-f77e-4c64-870b-dc93624b5967", "custom_id": "631044494", "risk": { "score": 0, "level": "low", "resource_name": "Bitstamp", "resource_category": "Exchange" }, "hosted_page_url": "https://business-hosted.cryptopay.me/channels/50eb5775-f77e-4c64-870b-dc93624b5967", "created_at": "2019-05-02T11:00:01+00:00" } } ``` It is important to note that `paid_amount` == `received_amount` + `fee`. It means that the full amount of the payment made by the customer consists of the `received_amount` and the `fee`, where the `received_amount` is the amount of the merchant balance credited to Cryptopay and the `fee` is the amount of the processing fee charged by Cryptopay. # Visual representation at Cashier Below is a good example of what details at your Cashier may look like:

The customer chooses Bitcoin and receives the details for the deposit - the channel address and QR code for making the payment from the mobile device.

Please note what details are shown to the customer: * QR code. To generate a QR code, it is necessary to use the content of the `uri` parameter, which you received in your response when creating the invoice: `"uri":"bitcoin:3Gtvf2EVxN8XJ4DHriRt9q9LkdVCpQZEeSd"`The QR code allows customers to make payments using a mobile device if the wallet is installed on it. The customer simply scans the QR code and the device opens the wallet with an automatically pre-filled payment destination address, which is a rather convenient method in the UX context {% hint style="info" %} Please note that not all wallets support this mechanism - it depends entirely on the wallet developer, but not on Cryptopay. {% endhint %} * The address the payment should be sent to {% hint style="warning" %} XRP and XLM channels must display additional field: * Destination tag for XRP * Memo ID for XLM Destination tag and Memo ID are similar to a reference number for bank transfers. They help to identify transactions when a single address is used by multiple users. They can be found in the address field of the response from server: `address: address?dt=destination_tag` {% endhint %} * The “Copy” buttons opposite the address for customers’ convenience The cryptocurrency icons that you can insert into your Cashier to indicate the payment method can be downloaded from [this link](https://developers.cryptopay.me/introduction/icons). Alternatively, instead of developing your own design, you can insert a ready-made [web page](/guides/channels/channel-hosted-page) with all the necessary payment details into your UI that looks [like this](https://hosted-business-sandbox.cryptopay.me/channels/e9c8e8dd-141f-4b52-b0f8-241fa62d3d8f). # Channel hosted page A channel hosted page is a web page that you can embed into your website to display the payment details of a particular channel to a customer.

There is a `hosted_page_url` attribute in the channel details that contains a URL to its hosted page. {% tabs %} {% tab title="API response example" %} ```javascript { "id": "50eb5775-f77e-4c64-870b-dc93624b5967", "name": "channel name", "description": "channel description", "receiver_currency": "EUR", "pay_currency": "BTC", "address": "2N9uVK2MDFNgBVqPnvCTV66Dinx3cp5J7S4", "network": "bitcoin", "project_id": "25632c89-7f40-4693-8ed0-99bf5f79d3a6", "custom_id": "631044494", "uri": "bitcoin:2N9uVK2MDFNgBVqPnvCTV66Dinx3cp5J7S4", "hosted_page_url": "https://business-hosted.cryptopay.me/channels/50eb5775-f77e-4c64-870b-dc93624b5967" } ``` {% endtab %} {% endtabs %} ## Settings You can apply different settings to hosted pages appearance like a specific locale by adding its acronym to the end of the `hosted_page_url` value via a query parameter. For example: [`https://business-hosted.cryptopay.me/channels/ecd7f89a-7754-47c5-bd82-2ec1ad072bc6` + `?locale=jp`](https://business-hosted.cryptopay.me/channels/ecd7f89a-7754-47c5-bd82-2ec1ad072bc6?locale=jp) Below is a list of variables you can use. | Parameter | Type | Description | | ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | locale | string | Can be `en`, `de`, `fr`, `es`, `pt`, `ru` and `jp` which means English, German, French, Spanish, Portuguese, Russian or Japanese language. If parameter is not set, the language will be taken from the browser settings. | | back\_button | boolean | Show/hide a back button on the page. This might be useful if you redirect customers to hosted pages. `false` if set by default | # Channel payment callbacks {% hint style="danger" %} Handling callbacks correctly is crucial to ensure your integration’s business logic works as expected. It is highly recommended to validate payment statuses and callbacks before acting on it inside your system. {% endhint %} Refer to [this section](/guides/api-basics/callbacks) to get more information on what callbacks are and how to validate them before acting on it inside your system. | Callback event | Description | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `created` | A customer has just broadcast their transaction on the network | | `completed` | The transaction has just been confirmed on the network. The channel payment status has been changed to `completed` | | `on_hold` | The received cryptocurrency transaction evaluated as High-Risk, therefore the Channel Payment transaction has been put on hold. Our Transaction Monitoring team will review this transaction to make a decision on whether we will be able to process this payment and add the funds to your merchant account balance or we will have to send the funds back to a sender. Refer to the [Risks](/guides/risks) section to get more details on what High-Risk transactions are and why we take it very seriously | | `refunded` | The funds have been returned back to the sender | | `cancelled` | The transaction was on the network but hasn't been confirmed within 14 days. The channel payment status has been changed to `cancelled` | {% tabs %} {% tab title="created" %} ```javascript { "data": { "id": "912345fb-6de2-4e50-9fae-b139c3c12345", "fee": "0.0", "risk": null, "txid": "aad38eb9a4b22fefa1234569bb78061120bb4b123458b650606765d1c8412345", "status": "pending", "address": "TC2Vxwky12345xwGcqPt2xy7jynvF12345", "network": "tron", "custom_id": "1234567", "channel_id": "17b12345-109a-4a27-af93-d955e4112345", "created_at": "2025-08-01T11:06:09+00:00", "customer_id": null, "paid_amount": "229.503834", "fee_currency": "TRX", "paid_currency": "TRX", "refund_address": null, "status_context": null, "received_amount": "0.0", "source_addresses": [ "TAzsQ9Gx8eq12345beXrbi45CuVPH12345" ], "received_currency": "TRX", "coin_withdrawal_id": null }, "type": "ChannelPayment", "event": "created" } ``` {% endtab %} {% tab title="completed" %} ```javascript { "data": { "id": "912345fb-6de2-4e50-9fae-b139c3c12345", "fee": "1.606527", "risk": { "level": "low", "score": 0, "resource_name": "Binance.com", "resource_category": null }, "txid": "aad38eb9a4b22fefa1234569bb78061120bb4b1234567850606765d1c8412345", "status": "completed", "address": "TC2Vxwky12345xwGcqPt2xy7jynvF12345", "network": "tron", "custom_id": "1234567", "channel_id": "17b12345-109a-4a27-af93-d955e4112345", "created_at": "2025-08-01T11:06:09+00:00", "customer_id": null, "paid_amount": "229.503834", "fee_currency": "TRX", "paid_currency": "TRX", "refund_address": null, "status_context": null, "received_amount": "227.897307", "source_addresses": [ "TAzsQ9Gx8eq12345beXrbi45CuVPH12345" ], "received_currency": "TRX", "coin_withdrawal_id": null }, "type": "ChannelPayment", "event": "completed" } ``` {% endtab %} {% tab title="on\_hold" %} ```javascript { "data": { "id": "57212345-1458-4c0e-8ca7-a4418b012345", "fee": "0.0", "risk": { "level": "high", "score": 0, "resource_name": "Kraken Market", "resource_category": null }, "txid": "0b8461234589c7bcc214de12345e9cd9b12345345d83f54eebb347f12345e8b2", "status": "on_hold", "address": "bc1qg12345j4a449nl2e12345kvzyplwfp7312345n9vpay812345vask12345", "network": "bitcoin", "custom_id": "1234567", "channel_id": "12345fe9-04f4-47d6-9668-12345123455e", "created_at": "2025-08-01T07:05:30+00:00", "customer_id": null, "paid_amount": "0.00382471", "fee_currency": "BTC", "paid_currency": "BTC", "refund_address": null, "status_context": "illicit_resource", "received_amount": "0.0", "source_addresses": [ "bc1qcax12345s23xpede12345fwdner96qudg12345" ], "received_currency": "BTC", "coin_withdrawal_id": null }, "type": "ChannelPayment", "event": "on_hold" } ``` {% endtab %} {% tab title="refunded" %} ```javascript { "data": { "id": "123454dc-0a4b-4288-9440-2bdf53c12345", "fee": "0.0", "risk": { "level": "low", "score": 0, "resource_name": null, "resource_category": null }, "txid": "1842ED39663952123456C1AA4D123455A592949123457F3B000023CB96112345", "status": "refunded", "address": "rHZMaubybZzb6fy12345zQw1Ax7R812345?dt=12345", "network": "ripple", "custom_id": "1234567", "channel_id": "2d612345-a4ae-48b2-8a07-569458612345", "created_at": "2025-07-30T12:09:30+00:00", "customer_id": null, "paid_amount": "0.0001", "fee_currency": "XRP", "paid_currency": "XRP", "refund_address": null, "status_context": null, "received_amount": "0.0001", "source_addresses": [ "rEni1epjkJfVXMmMaDD12345Fe1mY12345" ], "received_currency": "XRP", "coin_withdrawal_id": null }, "type": "ChannelPayment", "event": "refunded" } ``` {% endtab %} {% tab title="cancelled" %} ```javascript { "data": { "id": "0882c257-87de-4322-b4fa-4984ed912345", "fee": "0.0", "risk": null, "txid": "8263fc155dff13d6ddf812345cab04701dc3241e12345e205889a2ebf0412345", "status": "cancelled", "address": "bc1qft2kryup2nlu5a7rh123453mv8zlwmfgpct9dhagh123456ky6jqj12345", "network": "bitcoin", "custom_id": "1234567", "channel_id": "70512345-2833-4f10-a876-ec39c3b12345", "created_at": "2025-06-12T15:52:24+00:00", "customer_id": null, "paid_amount": "0.00020523", "fee_currency": "BTC", "paid_currency": "BTC", "refund_address": null, "status_context": null, "received_amount": "0.0", "source_addresses": [ "bc1qmz7ffpz39x5gd3q4d012345vd7hknfn9312345" ], "received_currency": "BTC", "coin_withdrawal_id": null }, "type": "ChannelPayment", "event": "cancelled" } ``` {% endtab %} {% endtabs %} # Automatic channel payment enrollment \ When you create a channel, you set a currency pair for it, meaning you get to choose the currency that the user sends and the currency that will be credited to your account. But occasionally a user can make a mistake and send some third currency e.g. when USDT via TRC-20 is sent instead of TRX via TRC-20 etc.\ Channel payments with incorrect coin (but correct network) are credited automatically as channel payments (with Custom ID of the original channel), and [callbacks](https://developers.cryptopay.me/guides/channels/callbacks) are sent. \ **Important points:**\ \ • The feature is only available if the user has sent incorrect coin via the correct network. If the network or both network and coin are incorrect, you can check the possibility of recovery [here](https://help.cryptopay.me/en/articles/5747828-recovery-of-incorrectly-sent-crypto-transactions). • The feature is only available for channels; it isn’t supported for invoices. • In such cases (when the end-user used an incorrect currency), **paid\_currency** for channel payment (in the callback) will differ from **pay\_currency** of the channel itself for those incorrect coin payments (it will match the actual currency that was sent and received on our side, as long as it’s supported by us). To ensure that such payments are credited correctly on your side, please check whether your integration would supports such a mismatch between the channel data and the callback; • The **received\_currency** (from the callback) will be the same as the **receiver\_currency** of the original channel, so if the end-user expected to get e.g. EUR as a result, this is the currency they’ll be credited with; • Even if the channel initially has **pay\_currency** = **receiver\_currency** (crediting payments with no exchange), with an incorrect coin there will be an exchange to **receiver\_currency** (so the current exchange rates would apply);\
# Invoices An invoice is a request for a cryptocurrency payment which is linked to its unique cryptocurrency address and the amount that has to be paid while the invoice is valid. The invoice amount can be expressed either in cryptocurrency or fiat currency. As cryptocurrency payments are made over a separate network, when creating an invoice, we generate a unique payment address for each cryptocurrency so we can match customers to their payments. When a customer makes a cryptocurrency payment, the transaction is then broadcast to the cryptocurrency network for validation/confirmation. Once the invoice is created, we start monitoring its unique address to identify the incoming transaction. Invoices have [statuses](/guides/invoices/invoice-statuses) and each time the invoice changes its status, Cryptopay sends [callbacks](/guides/api-basics/callbacks) to the Callback URL. Every time the customer sends cryptocurrency to the invoice address, we send the first callback with the `transaction_created` event. It means that the payment has just been identified, but it has not been validated by the network yet. When the transaction is completely verified and confirmed by the network, we send another callback with the `transacion_confirmed` event, and the invoice automatically changes its status from `new` to `completed`. The invoice is only valid for a limited time (10 minutes max). This is due to the fact that for each invoice Cryptopay freezes the exchange rate for 10 minutes. In some cases, customers make payments after the invoice has expired. In this case, the invoice status will be updated to `unresolved` with the `paid_late` context. There are also cases where customers may overpay or underpay the invoices. When this happens, the invoice changes its status to `unresolved` with an `overpaid` or `underpaid` context. In any of the above user scenarios, the `unresolved` payment status can be updated to `completed` or `refunded` manually, or Cryptopay will automatically update the status as soon as the payment is validated by the network if the appropriate settings have been selected on the Integration page > API > [How to handle unresolved invoices](/guides/invoices/how-to-handle-unresolved-invoices) in your account. # Invoice statuses Invoices have several `status` and `status_context` options. | status | status\_context | Description | | ------------ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `new` | `null` | An invoice has been created and Cryptopay is waiting for a transaction | | `completed` | `null` | The transaction has been processed successfully and the invoice amount credited to your account | | `unresolved` | `underpaid` | The invoice has been underpaid and must be resolved. Can be updated to `completed` or `refunded` | | `unresolved` | `overpaid` | The invoice has been overpaid and must be resolved. Can be updated to `completed` or `refunded` | | `unresolved` | `paid_late` | The invoice has been paid after the 10 minutes has passed and must be resolved. Can be updated to `completed` or `refunded` | | `unresolved` | `illicit_resource` | The received cryptocurrency transaction has been evaluated as High-Risk, therefore the payment has been put on hold. Can be updated to `completed` or `refunded` | | `refunded` | `null` | The full cryptocurrency transaction amount has been added to the merchant's cryptocurrency balance or sent back to the customer | | `cancelled` | `null` | The invoice hasn't been paid or the broadcasted transaction hasn't been confirmed on the network within 14 days | There are 3 other statuses besides `new` and `completed`. ### Cancelled The `cancelled` status is assigned to a payment if the transaction has not been confirmed on the blockchain network within 14 days from the moment the customer sent the funds to the invoice address. This may occur if the user has made a [double spend](https://en.bitcoin.it/wiki/Irreversible_Transactions#:~:text=Double%2Dspending%20is%20the%20result,the%20number%20of%20confirmations%20rises.) of funds and the network has not validated the payment. The second possible scenario, in which the invoice status will be updated from `new` to `cancelled`, is when the invoice has not been paid within 14 days. In both these cases, we will send a [callback](https://developers.cryptopay.me/guides/api-basics/callbacks) with the updated status. ### Unresolved In cases where a customer underpays, overpays or pays an invoice after 10 minutes, the invoice will change its status from `new` to `unresolved`. For all these scenarios, the relevant context will be given: `underpaid`, `overpaid` or `paid_late`. ### Refunded The `unresolved` status can be updated to `completed` or `refunded`, depending on how the merchant decides to receive such payment - to accept the funds received and complete the payment, or return the funds back to the sender. The `unresolved` status with the `illicit_resource` context is assigned to the payment when it has received a high risk level. In case you get a High-Risk payment it is required you contact us at . Our Transaction Monitoring team will review this transaction to make a decision on whether we will be able to reduce the risk level and process this payment, and add the funds to your account balance or we will have to send the funds back to the sender. Please refer to the [Risks](/guides/risks) section to get more details on what High-Risk transactions are and why we take it very seriously. Once the money has been sent back, the payment status will be changed to `refunded`. If the payment has not been returned to the sender but has been credited to the merchant's balance, the payment status will be changed to `refunded`. ## Invoice statuses diagram

You can also see [all the steps](/guides/invoices/payment-sequence) from the moment the invoice is created to the moment the payment is credited to the merchant account balance at Cryptopay. # Invoice payment sequence Invoice payment sequence.

Once an invoice is created, we start monitoring its cryptocurrency address to detect inbound transactions. 1. The customer specifies a purchase amount and purchase currency (if necessary) 2. The merchant makes an API call `POST /api/invoices` to [create an invoice](https://reference.cryptopay.me/#tag/Invoices/operation/invoices.create) 3. Cryptopay responds with the invoice details 4. The merchant displays the payment details to the customer (a destination wallet address, an exact amount to send, a QR code etc) 5. The customer broadcasts a cryptocurrency transaction 6. Cryptopay sends the 1st callback to notify the merchant about the fact that the customer has just broadcast their transaction 7. Cryptopay is waiting for the transaction to be confirmed on the network 8. Cryptopay sends the 2nd callback to notify the merchant about the fact that the transaction has been confirmed 9. Cryptopay changes the invoice status from `new` to `completed` and sends the final callback 10. The merchant makes an API call `GET /api/invoices/:id` to retrieve the invoice status 11. The invoice status is returned 12. The merchant marks the payment as successful on their side # How to handle unresolved invoices A payment that is in `unresolved` status must be authorised, otherwise the funds will be suspended. The `unresolved` status may be changed to the other two statuses - `completed` or `refunded` - depending on which option the merchant will select. Both statuses are final and cannot be changed to the other statuses in the future. The update of the payment status from `unresolved` to `completed` means that the payment has been completed and the funds have been credited to the merchant balance and the merchant can in turn replenish the balance of his customer on his side. Updating the payment status from `unresolved` to `refunded` means that the entire amount of cryptocurrency received will be credited to the merchant account balance or sent back to the merchant wallet (depending on which option the merchant has chosen) and such payment cannot be considered as successfully completed. You can update the status of a payment from `unresolved` to `completed` or `refunded` in two ways - manually from your account in the Transaction History section or automate this process on the Cryptopay side by selecting the appropriate settings in the Integration > API section. ### Manual update of the payment status To update the payment status manually, you will need to go to the Transaction history page in your account and find the payment you need. To do so, use the search fields and filters available on the Transaction history page.

In the search field at the very top of the page, you can insert the address to which the customer has sent the cryptocurrency, or TXID of the cryptocurrency payment. Our system will perform a database search to find out if we have registered such a payment and will give you the result. Alternatively, you can search the reference number of the payment by inserting it into the `custom_id` field in the table below. Alternatively, you can display a list of all `unresolved` payments with the context you need by selecting the required filters. After the right payment has been found, click on it to reveal its details. On the right, in the form of payment details, you will see all the events that have taken place with the payment so far.

At the bottom you will see two buttons - “Recalculate” and “Refund”. Press the button you need to get the result you want. {% hint style="info" %} Important: only one option is available for the Overpaid context in case of manual update of the payment status - Refund. In this case, not the entire cryptocurrency payment will be refunded, but only the extra amount. {% endhint %} #### Recalculate The incoming transaction will be recalculated at the new exchange rate. The invoice will change its status to `completed`.

#### **Refund** The incoming transaction will be refunded to the merchant’s cryptocurrency account or to an external wallet address. The invoice will change its status to `completed` or `refunded` depending on the invoice status context: * `underpaid` > Refund > `refunded` * `paid_late` > Refund > `refunded` * `overpaid` > Refund > `completed`

### Automatic update of the payment status You can also configure how to handle your unresolved invoices automatically on the Integration → API page in your account:

| Action | status\_context | Outcome | The final status will be | | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | Automatic recalculation at a new exchange rate and settlement |

underpaid

overpaid

paid\_late

| The received cryptocurrency transaction amount will be recalculated at a new exchange rate, and a new invoice amount will be settled | `completed` | | Automatic refund to a cryptocurrency account | `underpaid` | The full cryptocurrency transaction will be credited to the merchant’s cryptocurrency account on Cryptopay e.g. BTC to Bitcoin account | `refunded` | | | `overpaid` | The initial invoice amount will be settled. The cryptocurrency overage will be credited to the merchant’s cryptocurrency account on Cryptopay e.g. BTC to Bitcoin account | `completed` | | | `paid_late` | The full cryptocurrency transaction will be credited to the merchant’s cryptocurrency account on Cryptopay e.g. BTC to Bitcoin account | `refunded` | | Do nothing, I will handle them myself |

underpaid

overpaid

paid\_late

| You'll have to manually resolve the invoice by either recalculating or refunding it, which can be done in the account or via API |

completed

refunded

| We highly recommend using this automation and selecting the option "**Automatically recalculate at a new exchange rate and settle**" for all three `unresolved` contexts. This way, all your payments will be automatically assigned with the `completed` status, regardless of whether the payment is made late or the wrong amount has been sent to this payment. This can save a lot of time for your Support/Payment/Reconciliation teams and your customers without having to spend on communication and manual updating of the payment status.
# Underpaid ### Criteria `paid_amount` is less than `pay_amount` ### Callbacks to be sent in this scenario

Callback event	Invoice status	Invoice status context	Description
`transaction_created`	`new`	`null`	A customer has just broadcasted their transaction on the network but `paid_amount` is less than `pay_amount`
`transaction_confirmed`	`new`	`null`	The transaction has been confirmed on the network
`status_changed`	`unresolved`	`underpaid`	The invoice needs to be resolved
`status_changed`	`completed`	`null`	The transaction amount was exchanged at the new exchange rate. The final invoice amount may differ from the original one
`status_changed`	`refunded`	`null`	The whole transaction amount was refunded

Callback event	Invoice status	Invoice status context	Description
`transaction_created`	`new`	`null`	A customer has just broadcas their transaction on the network but `paid_amount` is greater than `pay_amount`
`transaction_confirmed`	`new`	`null`	The transaction has been confirmed on the network
`status_changed`	`unresolved`	`overpaid`	The invoice needs to be resolved
`status_changed`	`completed`	`null`	The transaction amount was exchanged at the new exchange rate. The final invoice amount may be different from the original one. OR The original invoice amount is added to the merchant's account balance and the overage is refunded

### API auto settings and status flow | API Auto Settings | Payment Flow | | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Do nothing, I will handle them myself | `new` → txn sent → txn confirmed → `unresolved:overpaid` | | Settle the invoice and automatically refund the overage to my crypto account | `new` → txn sent → txn confirmed → `unresolved:overpaid` → overage refunded → `completed` | | Automatically recalculate at a new exchange rate and settle | `new` → txn sent → txn confirmed → `unresolved:overpaid` → tx recalculated → `completed` | # Paid late ### Criteria The customer broadcasts their transaction after 10 minutes. ### Callbacks to be sent in this scenario

Callback event	Invoice status	Invoice status context	Description
`transaction_created`	`new`	`null`	A customer has just broadcasted their transaction on the network after 10 minutes
`transaction_confirmed`	`new`	`null`	The transaction has been confirmed on the network
`status_changed`	`unresolved`	`paid_late`	The invoice needs to be resolved
`status_changed`	`completed`	`null`	The transaction amount was exchanged at the new exchange rate. The final invoice amount may differ from the original one
`status_changed`	`refunded`	`null`	The whole transaction amount was refunded

### API auto settings and status flow | API Auto Settings | Payment Flow | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | Do nothing, I will handle them myself | `new` → invoice expired → txn sent → txn confirmed → `unresolved:paid_late` | | Automatically refund to my crypto account | `new` → invoice expired → txn sent → txn confirmed → `unresolved:paid_late` → tx refunded → `refunded` | | Automatically recalculate at a new exchange rate and settle | `new` → invoice expired → txn sent → txn confirmed → `unresolved:paid_late` → tx recalculated → `completed` | # Illicit resource A merchant cannot resolve the invoice that is assigned with the `status_context` of `illicit_resource` themselves. Instead, Cryptopay Transaction Monitoring team will review this transaction and contact the merchant to make a decision on whether Cryptopay will be able to process this payment and add the funds to the merchant account balance or we will have to send the funds back to a sender. {% hint style="info" %} We highly recommend making your Fraud Prevention and Transaction Monitoring teams aware of all such payments so that they contact us at . {% endhint %} Refer to the [Risks](/guides/risks) section to get more details on what High-Risk transactions are and why we take it very seriously. # Invoice refunds sequence | Invoice status | Invoice status context | Condition | Refund | | -------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | | `unresolved` | `underpaid` | `paid_amount` is less than `pay_amount` | A full transaction amount will be refunded | | `unresolved` | `overpaid` | `paid_amount` is greater than `pay_amount` | An extra amount will be refunded after that the original invoice amount will be credited to your account | | `unresolved` | `paid_late` | A transaction has been sent to a destination wallet address after the validity time period which is 10 minutes for fiat invoices and 2 hours for cryptocurrency invoices | A full transaction amount will be refunded | Navigate to the [Invoice statuses](/guides/invoices/invoice-statuses) section to get more information about invoice statuses. ## Underpaid {% tabs %} {% tab title="Refund to external address" %}

{% endtab %} {% tab title="Refund to your cryptocurrency account" %}

{% endtab %} {% endtabs %} ## Paid late {% tabs %} {% tab title="Refund to external address" %}

{% endtab %} {% tab title="Refund to your cryptocurrency account" %}

{% endtab %} {% endtabs %} ## Overpaid {% tabs %} {% tab title="Refund to external address" %}

{% endtab %} {% endtabs %} # Create an invoice Let's [create an invoice](https://reference.cryptopay.me/#tag/Invoices/operation/invoices.create) and then pay for it: {% code overflow="wrap" %} ```bash curl -X POST \ https://business-sandbox.cryptopay.me/api/invoices \ -H 'Authorization: HMAC ***' \ -H 'Content-Type: application/json' \ -H 'Date: Tue, 19 Mar 2019 10:11:40 GMT' \ -d '{"price_amount":"100", "price_currency":"EUR", "pay_currency":"BTC", "network":"bitcoin", "custom_id":"209584732"}' ``` {% endcode %} Let us go through the parameters we used in our request above: * `price_amount` - the payment amount * `price_currency` - the currency of payment, i.e. the currency into which the cryptocurrency received at the address of the invoice will be converted and in which the merchant will be credited to the balance, in our case it is `EUR` * `pay_currency` - the cryptocurrency in which the payment is to be made, in our case it is `BTC` * `network` - the blockchain in which the address is going to be created. The list of available networks can be found [here](https://developers.cryptopay.me/guides/currencies/currencies). * `custom_id` - we recommend you to specify a certain reference by which you associate your customer with the payment, e.g. `209584732` You will receive the invoice address, the amount of cryptocurrency to be sent to the invoice address and a link to the invoice's hosted page, which can be built into your website and other details: {% code overflow="wrap" %} ```json { "id": "cc75b958-5780-4b34-a33a-cf63b349fbab", "custom_id": "209584732", "status": "new", "status_context": null, "address": "3Gtvf2EVxN8XJ4DHriRt9q9LkdVCpQZEeSd", "network": "bitcoin", "uri": "bitcoin:3Gtvf2EVxN8XJ4DHriRt9q9LkdVCpQZEeSd?amount=0.010268", "price_amount": "100.0", "price_currency": "EUR", "pay_amount": "0.010268", "pay_currency": "BTC", "fee": "1.0", "fee_currency": "EUR", "paid_amount": "0.0", "exchange": { "pair": "BTCEUR", "rate": "4905.9838", "fee": "0.0", "fee_currency": "EUR" }, "transactions": [], "name": "invoice name", "description": "invoice description", "metadata": { "foo": "bar" }, "success_redirect_url": null, "hosted_page_url": "https://hosted-business.cryptopay.me/invoices/cc75b958-5780-4b34-a33a-cf63b349fbab", "created_at": "2019-05-02T13:56:56+00:00", "expires_at": "2019-05-02T14:06:56+00:00" } ``` {% endcode %} ## **Tips for Making Invoice Payments** To pay for the invoice, it’s required to send a cryptocurrency transaction to the invoice cryptocurrency address - in this tutorial it is `3Gtvf2EVxN8XJ4DHriRt9q9LkdVCpQZEeSd`. To do so, log in to your sandbox account and press the "Send" button, which is located on your cryptocurrency wallet balance:

In the pop-up window, enter the address (`address` from the received response) and the transaction amount (`pay_amount` from the received response), and complete the process. You can also automate this process with [this endpoint](https://reference.cryptopay.me/#tag/Coin-withdrawals/operation/coin-withdrawals.create) so that you do not have to create payments manually. Once the payment is made, we will send the [callbacks](/guides/api-basics/callbacks) to the Callback URL. {% hint style="info" %} We recommend that you check invoice statuses via `GET /api/invoices/:id`using [this endpoint](https://reference.cryptopay.me/#tag/Invoices/operation/invoices.retrieve) as the delivery of the callbacks is not guaranteed. {% endhint %} Below is an example of a callback for the final status `completed` of the payment: {% code overflow="wrap" %} ```json { "type": "Invoice", "event": "status_changed", "data": { "id": "cc75b958-5780-4b34-a33a-cf63b349fbab", "status": "completed", "status_context": null, "address": "2NG8f2EVxN8XJ4DHriRt9q9LkdVCpQZ2UGB", "network": "bitcoin", "price_amount": "100.0", "price_currency": "EUR", "pay_amount": "0.02038328", "pay_currency": "BTC", "paid_amount": "0.02038328", "exchange": { "pair": "BTCEUR", "rate": "4905.9838" }, "transactions": [ { "txid": "502e6de0c3b1d129974c55e6cd127fd548e4501ff8e8d9330ea9a30a83dbd16e", "risk": { "score": 3.1, "level": "low", "resource_name": "Bitstamp", "resource_category": "Exchange" } } ], "name": "invoice name", "description": "invoice description", "metadata": { "foo": "bar" }, "success_redirect_url": null, "hosted_page_url": "https://hosted-business.cryptopay.me/invoices/cc75b958-5780-4b34-a33a-cf63b349fbab", "custom_id": "209584732", "created_at": "2019-05-02T13:56:56+00:00", "expires_at": "2019-05-02T14:06:56+00:00" } } ``` {% endcode %} It is important to note that cash from the payment is only credited to the merchant balance when the payment status is updated to `completed`. The `price_amount` field for a payment with the status `completed` indicates the full amount of this processed payment. # Visual presentation at Cashier Below is a good example of what details at your Cashier might look like:

The customer chooses Bitcoin deposit method

![The merchant displays payment details to the customer](https://lh3.googleusercontent.com/8oOzziglINjN6BCZeTKOFqD_TxXps7lIEpp5DYQWB3NqwGfmaG_WXpnqrJYA8UDx-4MyAfTyzkuJjqvjEEfLwQSjQyN9busrFpwaegCL3v3E9JjNIWCvVfNqaDkSLSxc_4YhOWol) Please note what details are shown to the customer: * QR code. To generate a QR code, it is necessary to use the content of the `uri` parameter, which you received in your response when creating the invoice: `"uri":"bitcoin:3Gtvf2EVxN8XJ4DHriRt9q9LkdVCpQZEeSd?amount=0.010268"`The QR code allows customers to make payments using a mobile device if the wallet is installed on it. The customer simply scans the QR code and the device opens the wallet with an automatically pre-filled payment destination address, which is a rather convenient method in the UX context {% hint style="info" %} Please note that not all wallets support this mechanism - it depends entirely on the wallet developer, but not on Cryptopay. {% endhint %} * Payment amount in BTC * The address the payment should be sent to {% hint style="warning" %} XRP and XLM invoices must display additional field: * Destination tag for XRP * Memo ID for XLM Destination tag and Memo ID are similar to a reference number for bank transfers. They help to identify transactions when a single address is used by multiple users. They can be found in the address field of the response from server: `address: address?dt=destination_tag` {% endhint %} * The “Copy” buttons opposite the payment amount and address for customers’ convenience * Timer with a countdown of the time during which the payment is to be made You can download cryptocurrency icons [here. ](https://developers.cryptopay.me/introduction/icons)Alternatively, you can insert a ready [hosted page](/guides/invoices/invoice-hosted-page) with all the necessary payment details into your UI, which looks [like this](https://hosted-business-sandbox.cryptopay.me/channels/e9c8e8dd-141f-4b52-b0f8-241fa62d3d8f). # Invoice hosted page An invoice hosted page is a web page that you can embed into your website to display the payment details of a particular invoice to a customer. There is a `hosted_page_url` attribute in the invoice details that contains its hosted page URL.

{% tabs %} {% tab title="API response example" %} ```javascript { "id": "cc75b958-5780-4b34-a33a-cf63b349fbab", "custom_id": "209584732", "status": "new", "status_context": null, "address": "2NG8f2EVxN8XJ4DHriRt9q9LkdVCpQZ2UGB", "network": "bitcoin", "uri": "bitcoin:2NG8f2EVxN8XJ4DHriRt9q9LkdVCpQZ2UGB?amount=0.02038328", "price_amount": "100.0", "price_currency": "EUR", "pay_amount": "0.02038328", "pay_currency": "BTC", "fee": "1.0", "fee_currency": "EUR", "paid_amount": "0.0", "exchange": { "pair": "BTCEUR", "rate": "4905.9838", "fee": "0.0", "fee_currency": "EUR" }, "transactions": [], "name": "invoice name", "description": "invoice description", "metadata": { "foo": "bar" }, "success_redirect_url": null, "hosted_page_url": "https://business-hosted.cryptopay.me/invoices/cc75b958-5780-4b34-a33a-cf63b349fbab", "created_at": "2019-05-02T13:56:56+00:00", "expires_at": "2019-05-02T14:06:56+00:00" } ``` {% endtab %} {% endtabs %} ## Settings You can apply different settings to hosted pages appearance like a specific locale by adding its acronym to the end of the `hosted_page_url` value via a query parameter. For example: [`https://business-hosted.cryptopay.me/invoices/b5cb2b8a-aa26-4b6b-b578-0fcc46c1f3a0` + `?locale=jp`](https://business-hosted.cryptopay.me/invoices/b5cb2b8a-aa26-4b6b-b578-0fcc46c1f3a0?locale=jp) Below is a list of variables you can use. | Parameter | Type | Description | | ------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | locale | string |

Can be en, de, fr, es, pt, ru and jp which means English, German, French, Spanish, Portuguese, Russian or Japanese language.

If parameter is not set, the language will be taken from the browser settings.

| | back\_button | boolean | Show/hide a back button on the page. This might be useful if you redirect customers to hosted pages. `false` if set by default | ## Transaction created As soon as a sender broadcasts the transaction, you'll receive a callback with the following attributes: `"event": "transaction_created"` ## Status changed You'll receive one more callback when the invoice changes its status to one of the final ones (`completed` or `refunded`) upon transaction confirmation: `"event": "status_changed"`

## Invoice expired

# Online checkout Merchants do not always need custom API integration. In order to accept payments, Merchant can save time and integrate our [online checkout](https://demo-business-sandbox.cryptopay.me/). An online checkout is a ready-made tool based on [invoices](https://developers.cryptopay.me/guides/invoices), that you can plug into your website and start accepting cryptocurrency payments without integrating the API. The checkout is designed both for desktop and mobile web browsers. It can be used as a pop-up or embedded part of your website. Check this demo [https://demo-business-sandbox.cryptopay.me](https://demo-business-sandbox.cryptopay.me/) to see what it looks like.

# How-to ## Step 1 * Log in to your Cryptopay account * Navigate to Integration → Online checkout * Generate a new key

## Step 2 Add the following meta tags to your web page. ```markup ... ... ``` ## Step 3 Add the following code to your web page. {% tabs %} {% tab title="HTML" %} ```markup