CoinwayPAY API

Hosted Payment Page

The CoinwayPAY Payment Page (CPP) is an online checkout solution which combines a highly customizable user interface with payment processing for crypto payments. Integrate the Hosted Payment Page (HPP) to redirect the consumer from your shop to a standalone payment page hosted by CoinwayPAY.

If you have any questions, please contact

Getting Started

To integrate the Hosted Payment Page (HPP) in your shop, use a simple backend-to-backend JSON Workflow for the payment process.

  1. Create a payment: You send an initial POST request with details of the transaction to the CPP. This POST request is secured by basic access authentication.
  2. Redirect the consumer to the payment page: Use the response URL to redirect the consumer to the payment page. The consumer makes the payment on the site and submits it.
  3. Parse and process the payment response: The payment is processed. Depending on the result (successful, pending, failed or canceled), the consumer is redirected to the respective page. The CPP sends a POST request containing payment data to the same URL. It is highly recommended that you parse and process this response to verify the payment.
  4. The payment process is complete.

Create a Payment

To create a payment session, send a POST request to the /w/register endpoint, e.g.

This is an HTTP request with two headers:

Content-Type: application/json Authorization: Basic NzAwMDAtQVBJREVNTy1DQVJEOm9oeXNTMC1kdmZNeA==

The Authorization header needs to be formatted as: "Authorization"="Basic" + base64("username:password")


{ "walletId": "7a6dd74f-06ab-4f3f-a864-adc52687270a", "referenceId": "O123412", "amount": 10, "currency": "EUR", "successRedirectUrl": "", "failRedirectUrl": "", "cancelRedirectUrl": "", "cryptoCurrency": "BTC" }
Parameter Example Description
walletId "11c2be...4435" The internal CoinwayPAY wallet id.
referenceId "123" The reference number for the payment (e.g. invoice number).
amount 15 The amount to pay in fiat currency.
currency "EUR" The target currency to use (must match the wallet currency).
successRedirectUrl "https://.../success" The URL redirected after successfull payment.
failRedirectUrl "https://.../failed" The URL redirected after failed payment.
cancelRedirectUrl "https://.../cancel" The URL redirected after canceled payment.


{ "success": true, "redirectUrl": "", "errorCode": 0, "errorMessage": "" }

Use the payment-redirect-url to redirect the consumer. You can implement the redirection in any way that suits you best.

PHP Example

An example to call the create payment api with php and the GuzzleHttp client.

$apiPassword = ''; $apiUser = ''; $payment_details = [ "walletId" => "7a6dd74f-06ab-4f3f-a864-adc52687270a", "referenceId" => O123412", "amount" => 10.0, "currency" => "EUR", "successRedirectUrl" => "", "failRedirectUrl" => "", "cancelRedirectUrl" => "" ]; $header = [ "Content-Type" => " application/json", "Authorization" => " Basic " . base64_encode($apiUser . ':' . $apiPassword), "Accept" => " application/json", ]; $client = new GuzzleHttp\Client(); $options = [ 'headers' => $header, 'json' => $payment_details ]; $response = $client->post("", $options); print_r($response->getStatusCode()); print_r($response->getBody()->getContents());

Parse and Process the Payment Response

After the customer completed the payment process, the success, fail or cancel url will be called with an HTTP Post Request. The Request will include details of the transaction and the result. The data is encoded with base64 encoding and contains an additional signature (HMAC SHA-25) to validate the request. The signature key is provided with the credentials of the plattform.

Request headers

accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3 accept-encoding: gzip, deflate, br accept-language: de-DE,de;q=0.9,en-US;q=0.8,en;q=0.7 cache-control: max-age=0 content-length: 533 content-type: application/x-www-form-urlencoded cookie: ARRAffinity=1e265b5431b24c2b105a13bc1ac254f095bed59fa8ef37b02f0b2623f4873d30 origin: referer: sec-fetch-mode: navigate sec-fetch-site: same-site upgrade-insecure-requests: 1 user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.87 Safari/537.36

Request body url-encoded


Request Values

dataB64: eyJwYXltZW50SWQiOiJiMWFmM2MwOC05NmE0LTQzMjgtOTFiZi0wYmM0ODFhNDdiY2EiLCJzZXNzaW9uSWQiOiIwMzk0YWZhMy1mYzFmLTRlYzgtODMxMi02ODYwYWUyMzFkYTkiLCJ3YWxsZXRJZCI6IjkxN2U3MTE3LThmMTEtNGFjOS05NDk5LTZjNjAwNjRlNGYwYiIsImFtb3VudCI6MTI0Ljg1MDAwMDAwLCJjdXJyZW5jeSI6IkVVUiIsIm1lc3NhZ2UiOiJSMTkwNi8xMDI1Iiwic3RhdGUiOiJSZWNlaXZlZCIsInN1Y2Nlc3NmdWwiOnRydWUsImlucHV0QW1vdW50IjowLjAxMzMyNjg2LCJpbnB1dEN1cnJlbmN5IjoiQlRDIiwidHJhbnNhY3Rpb25JZCI6ImQ1Mzk0MzQ4LWExMzItNGEzZi1hYjZkLTc4ODMwN2ZhNGMzZiIsImlzVGVzdG5ldCI6dHJ1ZX0= signature: SE1eU1vEjIptCPkirnPPNQemc9NdPpc+idBX1BKubD8=


The parsed value from the dataB64 of the request in JSON format.

{ "paymentId": "b1af3c08-96a4-4328-91bf-0bc481a47bca", "sessionId": "0394afa3-fc1f-4ec8-8312-6860ae231da9", "walletId": "917e7117-8f11-4ac9-9499-6c60064e4f0b", "amount": 124.85, "currency": "EUR", "message": "R1906/1025", "state": "Received", "successful": true, "inputAmount": 0.01332686, "inputCurrency": "BTC", "transactionId": "d5394348-a132-4a3f-ab6d-788307fa4c3f", "isTestnet": true }
Parameter Example Description
paymentId "11c2be...4435" The internal CoinwayPAY payment id.
sessionId "aeb8ce...94bc" The internal CoinwayPAY session id.
walletId "7a6dd7...270a" The CoinwayPAY wallet id.
transactionId "d5394...4c3f" The CoinwayPAY Transaction id. (Only available when the state is received)
amount 10 The Amount.
currency EUR The currency of the amount.
Message "O123412" The message / reference of this payment.
Label "ExampleCompany" The label of the current company of the payment.
state "Received" The state of the Payment. Available States are:
  • Created: The Session war internally created (only internally usage).
  • Waiting: The Session is awaiting payment (only internally usage).
  • Receiving: The Payment is pending and not proccessed by the blockchain (only internally usage).
  • Received: The Session was received.
  • Cancelled: The Session was cancelled by the user.
  • Timeout: The Session has timed out. (Error state)
  • InvalidAmount: An invalid amount was transmitted and will be returned to the sender. (Error state)
  • ExceedDailyLimit: The amount exceed the daily transaction limit. (Error state)
  • ExceedSessionLimit: The amount exceed the session transaction limit. (Error state)
successful true Indicates, if the request was successful or not.
inputAmount 0.00010 The amount in the input currency
inputCurrency "BTC" The input currency, selected by the client
isTestnet true Indicates an testnet transaction. Only available, when a testnet transaction was started.

Get Payment Status

If required, you can get the status of an payment by reference via API.



Provide your reference in the {reference} section.

This is an HTTP request with two headers:

Content-Type: application/json Authorization: Basic NzAwMDAtQVBJREVNTy1DQVJEOm9oeXNTMC1kdmZNeA==

The Authorization header needs to be formatted as: "Authorization"="Basic" + base64("username:password")


{ "reference": "string", "id": "string", "dataBase64": "base64 encoded string", "signature": "base64 encoded signature" }

The data is provided in the dataBase64 property and encoded with Base64. For signature validation see "Signature Validation" The data has the same format as the Payment Result.

Signature Validation

To validate the signature, create an HMAC SHA-256 of the data with the signature password and compare the signature with the transmitted signature in the request.

Example C#

var dataBase64 = "eyJwYXltZW50SWQiOiJiMWFmM2MwOC05NmE0LTQzMjgtOTFiZi0wYmM0ODFhNDdiY2EiLCJzZXNzaW9uSWQiOiIwMzk0YWZhMy1mYzFmLTRlYzgtODMxMi02ODYwYWUyMzFkYTkiLCJ3YWxsZXRJZCI6IjkxN2U3MTE3LThmMTEtNGFjOS05NDk5LTZjNjAwNjRlNGYwYiIsImFtb3VudCI6MTI0Ljg1MDAwMDAwLCJjdXJyZW5jeSI6IkVVUiIsIm1lc3NhZ2UiOiJSMTkwNi8xMDI1Iiwic3RhdGUiOiJSZWNlaXZlZCIsInN1Y2Nlc3NmdWwiOnRydWUsImlucHV0QW1vdW50IjowLjAxMzMyNjg2LCJpbnB1dEN1cnJlbmN5IjoiQlRDIiwidHJhbnNhY3Rpb25JZCI6ImQ1Mzk0MzQ4LWExMzItNGEzZi1hYjZkLTc4ODMwN2ZhNGMzZiIsImlzVGVzdG5ldCI6dHJ1ZX0="; var transmittedSignature = "SE1eU1vEjIptCPkirnPPNQemc9NdPpc+idBX1BKubD8="; var signatureKey = "27c5679e723c45768f90c07e37e91cc917f9366f23a0412f932cf07e8a7d1020"; var key = Convert.FromBase64String(signatureKey); var message = Convert.FromBase64String(dataBase64); var hash = new HMACSHA256(key); var hashData = hash.ComputeHash(message); var calculatedSignature = Convert.ToBase64String(hashData); Assert.AreEqual(transmittedSignature, calculatedSignature);

Example PHP

$dataBase64 = "eyJwYXltZW50SWQiOiJiMWFmM2MwOC05NmE0LTQzMjgtOTFiZi0wYmM0ODFhNDdiY2EiLCJzZXNzaW9uSWQiOiIwMzk0YWZhMy1mYzFmLTRlYzgtODMxMi02ODYwYWUyMzFkYTkiLCJ3YWxsZXRJZCI6IjkxN2U3MTE3LThmMTEtNGFjOS05NDk5LTZjNjAwNjRlNGYwYiIsImFtb3VudCI6MTI0Ljg1MDAwMDAwLCJjdXJyZW5jeSI6IkVVUiIsIm1lc3NhZ2UiOiJSMTkwNi8xMDI1Iiwic3RhdGUiOiJSZWNlaXZlZCIsInN1Y2Nlc3NmdWwiOnRydWUsImlucHV0QW1vdW50IjowLjAxMzMyNjg2LCJpbnB1dEN1cnJlbmN5IjoiQlRDIiwidHJhbnNhY3Rpb25JZCI6ImQ1Mzk0MzQ4LWExMzItNGEzZi1hYjZkLTc4ODMwN2ZhNGMzZiIsImlzVGVzdG5ldCI6dHJ1ZX0="; $signatureKey = "27c5679e723c45768f90c07e37e91cc917f9366f23a0412f932cf07e8a7d1020"; $transmittedSignature = "SE1eU1vEjIptCPkirnPPNQemc9NdPpc+idBX1BKubD8="; $calculatedSignature = base64_encode(hash_hmac('sha256', base64_decode($dataBase64), base64_decode($signatureKey), true)); if($transmittedSignature == $calculatedSignature) { echo 'success'; } else { echo 'failed'; }

Rates API

The CoinwayPAY Rates API provides a direct access to the currency rates used in CoinwayPAY.

To get rate informations, send a GET request to the /r/pairs endpoint, e.g.

The requests needs 2 HTTP Headers:

Content-Type: application/json Authorization: Basic NzAwMDAtQVBJREVNTy1DQVJEOm9oeXNTMC1kdmZNeA==

The Authorization header needs to be formatted as: "Authorization"="Basic" + base64("username:password")


The respone contains an array of currency pairs with the currency rate from CoinwayPAY.

{ "items": [ { "source": "XIN", "target": "EUR", "rate": 0.00110000 }, { "source": "STO", "target": "EUR", "rate": 2.54000000 }, { "source": "BTC", "target": "EUR", "rate": 7957.90000000 }, { "source": "ETH", "target": "EUR", "rate": 168.91000000 } ], "success": true, "errorCode": 0, "errorMessage": null }

Address API

The CoinwayPAY Address API provides a simple way to receive crypto payments in your own application or website.

If you have any questions, please contact

Getting Started

First, you will need your API Keys, which we provide for Bitcoin and the Bitcoin Testnets. You can get your API-Key from our Support-Team. You are required to use an API Key when you interact with the CoinwayPAY Address API. It tells CoinwayPAY which network (e.g., Bitcoin Mainnet) you wish to perform actions on.

You can access the API by making calls to links of this format: API KEY

Actions for Handling Addresses

Get New Address

Returns a newly generated address, and its unique(!) label generated by CoinwayPAY. You can optionally specify a custom label.

Get a new address with a random label

/api/v2/get_new_address/?api_key=API KEY

Get a new address with a given label

/api/v2/get_new_address/?api_key=API KEY&label=LABEL

Get Balance

Returns the balance of your entire Bitcoin account (i.e., the sum of balances of all addresses/users within it) as numbers to 8 decimal points, as strings.

/api/v2/get_balance/?api_key=API KEY

Get My Addresses

Returns the addresses, their labels, user id, and balances on your account. Upto 2500 addresses per page. Page parameter is optional.

/api/v2/get_my_addresses/?api_key=API KEY&page=PAGE NUMBER

Get Address Balance

Returns the balance of the specified addresses, or labels. Upto 2500 addresses/labels can be specified per request.

Get the balance of a given address

/api/v2/get_address_balance/?api_key=API KEY&addresses=ADDRESS1,ADDRESS2,...

Get the balance of an address with a given label

/api/v2/get_address_balance/?api_key=API KEY&labels=LABEL1,LABEl2,...

Misc. Actions

Get Current Price

Returns the prices for Bitcoin specified by the API Key.

/api/v2/get_current_price/?api_key=API KEY&price_base=BASE CURRENCY