LogoLogo
  • General
    • Welcome to 0xpay
    • Transaction Fees
    • Networks & Assets
  • Integration Cookbook
    • Getting Started
      • Merchant Setup
    • Receive assets
    • Send assets
    • Invoices
    • Exchanges
  • Public API
    • Authorization
      • Signature Examples
    • Endpoints
      • Merchant
      • Basic crypto operations
      • Crypto Invoices
      • Basic Fiat Operations
      • Fiat Invoices
      • Exchange
      • Exchange + Withdrawal
    • Notifications
      • Crypto Callbacks
      • Fiat Callbacks
      • Exchange Callbacks
    • JS/TS SDK
      • Getting started
      • Processing WebHook Notifications
      • Reference
  • Legal Info
    • Terms of Service
      • ANNEX 1: RISK DISCLOSURE
      • ANNEX 2: PROHIBITED BUSINESSES
      • ANNEX 3: HIGH-RISK STATES, TERRITORIES AND JURISDICTIONS
    • Privacy Policy
Powered by GitBook
On this page
  • Building the signature
  • Signing a request
  • Verifying a notification (webhook)
  • Signature Examples
  1. Public API

Authorization

PreviousExchangesNextSignature Examples

Last updated 2 years ago

In order to authorize your requests, get a .

Authorization is required:

  • To verify your request and prove your ownership of the merchant.

  • To verify notifications (webhooks) that 0xpay sending to your server to verify the authority.

Building the signature

General formula is:

signature = hmacsha256(method + url + body + timestamp, privateKey)

Overall guide to build your signature is described below:

  1. Concatenate HTTP method(POST, GET, etc), URL path, request body (or an empty string, if the body is empty), and timestamp in seconds. Let's call resulted string <MESSAGE>

  2. Sign received <MESSAGE> using algorithm with merchant's <PRIVATE_KEY>. Let's call resulted hash <SIGNATURE>

Signing a request

To make a valid request, you have to include several headers along with it:

Header
Value

merchant-id

Copy it from your 0xpay Dashboard -> Merchant Settings section.

signature

<SIGNATURE>

timestamp

<TIMESTAMP>

For example, I want to create an address in the BITCOIN network. I have to POST /merchants/addresses the API endpoint. Here is my payload:

{
  "meta":  "<my-user-id>",
  "blockchain":  "BITCOIN"
}

Let's say, that my current timestamp is 1650289480 (in seconds!!!). Lets concatenate parts of our request and we will receive next <MESSAGE>:

POST/merchants/addresses{
  "meta": "<my-user-id>",
  "blockchain": "BITCOIN"
}1650289480

As far as we already generated <SIGNATURE>, we can make a request.

Code examples:

const merchantId = 'b2a46898-7e6d-4c13-8a31-47154c43ee8b'
const key = "bd4c0f27382cbdf0c52318a99308fc6d"
const timestamp = Math.floor(Date.now() / 1000)
const path = ('your-path-to-method')
const sign = CryptoJS.HmacSHA256(request.method + path + request.body + timestamp, key).toString()

Verifying a notification (webhook)

Body of the webhook is:

{
  "id": "some-id",
  "from": "some-address",
  "ticker": "BTC",
  "blockchain": "BITCOIN",
  "kind": "Replenish",
  "block": "1000",
  "status": "Confirmed",
  "time": 123123123
}

Header of the request:

SIGNATURE: some-random-signature
TIMESTAMP: 1652887112
POSTdomain.com/webhooks/0xpay{
  "id": "some-id",
  "from": "some-address",
  "ticker": "BTC",
  "blockchain": "BITCOIN",
  "kind": "Replenish",
  "block": "1000",
  "status": "Confirmed",
  "time": 123123123
}1652887112

Now you can generate the signature using the formula mentioned above and compare it with the SIGNATURE we sent you in headers. If signatures match, then the request is original.

Signature Examples

Let's build exemplary signatures for each of our requests in order to demonstrate the logic behind this process. In this case, we can equal values for

Then, I will receive <SIGNATURE> using with the private key.

Let's assume that you receive some replenishment webhook sent from 0xpay server, that is directed to some domain.com/webhooks/0xpay endpoint you have specified earlier in the .

So then build the <MESSAGE> mentioned

HMAC-SHA256
above
HMAC-SHA256
private key
merchant's settings