URL signing

MoonPay is highly committed to security. For this reason, whenever sensitive information such as emails or wallet addresses are transmitted to the widget, you are required to use the signature parameter, otherwise the MoonPay widget fails to load. This measure makes it more difficult for unauthorized third parties to misuse the widget’s pre-fill feature. A signed URL helps limit access from unauthorized third parties by providing limited permissions and time to make a request. Passing the signature parameter is mandatory if you’re using the walletAddress or walletAddresses parameter and it must be appended at the end of the URL. If your widget URL contains sensitive information, use the signature parameter. You can generate a signature of the URL server-side and append it to the end of the URL. If the signature is provided, we’ll check the validity of the query string to make sure it has not been altered. If the signature is invalid for any reason the MoonPay widget will fail to load.

How to sign URLs

Follow these steps for signing URLs:

Send your widget URL to your backend server.
Generate the signature using the secret key found in your MoonPay dashboard.
- Use your own code to generate signatures and sign URLs
- Alternatively, use our Node SDK to generate signatures, sign URLs, and validate signatures.
Return either the signature or entire signed URL.
- If using a SDK, return the signature and use updateSignature. Do not encode the signature, as the SDK handles this.
- If using a URL-based integration, return the entire signed URL. Make sure the value of signature and other parameters are URL-encoded.
Show the widget using the SDK or URL.

Returning the signature vs entire signed URLIntegrations using an SDK: Return the signature by itself and use updateSignatureIntegrations using URLs: Return the entire signed URL

How to generate signatures

Create an HMAC (Hash-Based Message Authentication Code) using the SHA-256 hash function.
1. Use your secret API key as the key and the original URL’s query string as the message.
For URL-based integrations, make sure all query parameter values are URL-encoded before creating the signature.

All query parameter values (not the entire query string) need to be URL-encoded before generating the signature for it to be valid.

Code examples

Integrations using an SDK

Integrations using a web or mobile SDK should calculate the signature, then return the signature by itself, not URL-encoded. More details about signing with each SDK:

import crypto from 'crypto';

const secretKey = 'sk_test_key'; // Use your secret key

const generateSignature = (url) => {
const signature = crypto
.createHmac('sha256', secretKey)
.update(new URL(url).search) // Use the query string part of the URL
.digest('base64'); // Convert the result to a base64 string

    console.log(signature) // Print the signature
    return signature // Return the signature

};

<?php
  $host = 'https://buy-sandbox.moonpay.com';  // Base URL
  $query = '?apiKey=pk_test_key&currencyCode=eth&walletAddress=0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae';  // Query parameters

  $secretKey = 'sk_test_key';  // Your secret key

  // Create the HMAC SHA-256 hash and encode it in base64
  $signature = base64_encode(hash_hmac('sha256', $query, $secretKey, true));

  echo $signature;  // Print the signature
?>

Integrations using URLs

Integrations generating widget URLs should calculate the signature, URL-encode the signature, then return the whole signed URL.

import crypto from 'crypto';

const originalUrl = '<https://buy-sandbox.moonpay.com?apiKey=pk_test_key&currencyCode=eth&walletAddress=0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae>';

const signature = crypto
.createHmac('sha256', 'sk_test_key') // Use your secret key
.update(new URL(originalUrl).search) // Use the query string part of the URL
.digest('base64'); // Convert the result to a base64 string

const urlWithSignature = `${originalUrl}&signature=${encodeURIComponent(signature)}`; // Add the signature to the URL

console.log(urlWithSignature); // Print the signed URL

<?php
  $host = 'https://buy-sandbox.moonpay.com';  // Base URL
  $query = '?apiKey=pk_test_key&currencyCode=eth&walletAddress=0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae';  // Query parameters

  $secretKey = 'sk_test_key';  // Your secret key

  // Create the HMAC SHA-256 hash and encode it in base64
  $signature = base64_encode(hash_hmac('sha256', $query, $secretKey, true));

  // URL encode the signature
  $encodedSignature = urlencode($signature);

  // Combine the base URL, query parameters, and the signature
  $signedUrl = $host . $query . "&signature=" . $encodedSignature;

  echo $signedUrl;  // Print the signed URL
?>

import base64
import hashlib
import hmac
from urllib.parse import quote, urlsplit

original_url = "https://buy-sandbox.moonpay.com/?apiKey=pk_test_key&currencyCode=eth&walletAddress=0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae"
secret_key = b"sk_test_key"  # Use your secret key

query = "?" + urlsplit(original_url).query  # The query string, including the leading ?
signature = base64.b64encode(
    hmac.new(secret_key, query.encode(), hashlib.sha256).digest()
).decode()

signed_url = f"{original_url}&signature={quote(signature, safe='')}"
print(signed_url)

require "openssl"
require "base64"
require "uri"
require "cgi"

original_url = "https://buy-sandbox.moonpay.com/?apiKey=pk_test_key&currencyCode=eth&walletAddress=0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae"
secret_key = "sk_test_key" # Use your secret key

query = "?" + URI.parse(original_url).query # The query string, including the leading ?
signature = Base64.strict_encode64(
  OpenSSL::HMAC.digest("sha256", secret_key, query)
)

signed_url = "#{original_url}&signature=#{CGI.escape(signature)}"
puts signed_url

package main

import (
  "crypto/hmac"
  "crypto/sha256"
  "encoding/base64"
  "fmt"
  "net/url"
)

func main() {
  originalURL := "https://buy-sandbox.moonpay.com/?apiKey=pk_test_key&currencyCode=eth&walletAddress=0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae"
  secretKey := "sk_test_key" // Use your secret key

  u, _ := url.Parse(originalURL)
  query := "?" + u.RawQuery // The query string, including the leading ?

  mac := hmac.New(sha256.New, []byte(secretKey))
  mac.Write([]byte(query))
  signature := base64.StdEncoding.EncodeToString(mac.Sum(nil))

  signedURL := originalURL + "&signature=" + url.QueryEscape(signature)
  fmt.Println(signedURL)
}

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URI;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class SignUrl {
  public static void main(String[] args) throws Exception {
    String originalUrl = "https://buy-sandbox.moonpay.com/?apiKey=pk_test_key&currencyCode=eth&walletAddress=0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae";
    String secretKey = "sk_test_key"; // Use your secret key

    // The query string, including the leading ?
    String query = "?" + URI.create(originalUrl).getRawQuery();

    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    String signature = Base64.getEncoder().encodeToString(mac.doFinal(query.getBytes(StandardCharsets.UTF_8)));

    String signedUrl = originalUrl + "&signature=" + URLEncoder.encode(signature, StandardCharsets.UTF_8);
    System.out.println(signedUrl);
  }
}

Attention: The API gateway of some cloud providers change your parameter’s order, resulting in a failed signature validation.

Verify your implementation

Run your signing code against this fixed input and compare the output. If it matches, your implementation is correct and any remaining problem is in the URL you sign, not in your code.

Input	Value
Secret key	`sk_test_DocsVector00`
URL before signing	`https://buy-sandbox.moonpay.com/?apiKey=pk_test_DocsVector00&currencyCode=eth&walletAddress=0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe`
Message to sign	`?apiKey=pk_test_DocsVector00&currencyCode=eth&walletAddress=0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe`
Expected signature (base64)	`oIJxSghyzll/BLhUFdQZhkxf7DAS8REFaWr/ibO+K8Q=`
Signature, URL-encoded	`oIJxSghyzll%2FBLhUFdQZhkxf7DAS8REFaWr%2FibO%2BK8Q%3D`

The signed URL is the original URL with &signature=oIJxSghyzll%2FBLhUFdQZhkxf7DAS8REFaWr%2FibO%2BK8Q%3D appended. The keys in this vector are placeholders for documentation and are not real credentials. Two details this vector checks:

The message includes the leading ?. If your code produces z2PF5gVnemAZat6jSnLdgG7MB9SNX1TCrRc2bkHq8DQ=, you are signing the query string without the ?.
This signature happens to contain +, / and =, so it also exercises the URL encoding step. Append the URL-encoded form.

Troubleshooting

Signing failures return HTTP 400 with moonPayErrorCode: 1_SYS_UNKNOWN. That code does not mean an internal error: the message field states the real cause (Invalid signature, Missing signature, Invalid API key). See Errors for why.

Symptom	Fix
Your output does not match the test vector above	You are signing the wrong message. Sign only the query string, including the leading `?`. Do not include the scheme, host, or path.
Signatures fail only when values contain special characters (emails, some wallet addresses)	You are signing different bytes than you send. URL-encode the parameter values first, then sign the resulting query string.
Signatures fail intermittently, on roughly half of generated URLs	The signature is appended without URL encoding. Base64 output contains `+` about half the time, and an unencoded `+` decodes as a space on our side. URL-encode the signature value.
Your algorithm matches the vector but real URLs still fail	Wrong key. Sign with the secret key (`sk_test_` or `sk_live_`) from the same environment as the `apiKey` in the URL. The publishable key never signs.
`Invalid signature` only in production infrastructure	A gateway or CDN between you and the customer reorders or re-encodes query parameters after you sign. Sign the final URL as it leaves your system, and compare what the widget receives with what you signed.
Signature breaks after you add a parameter	Any change to the query string after signing invalidates it, including appending parameters client-side. Build the complete URL first, sign it, and append the signature last.
`Missing signature`	The URL carries a parameter that requires signing (for example `walletAddress`) but has no `signature` parameter.

Key rotation is safe: while two secret keys are active on your account, signatures from either key are accepted.

Get Started

On-Ramp

Off-Ramp

How to sign URLs

How to generate signatures

Code examples

Integrations using an SDK

Integrations using URLs

Verify your implementation

Troubleshooting

​How to sign URLs

​How to generate signatures

​Code examples

​Integrations using an SDK

​Integrations using URLs

​Verify your implementation

​Troubleshooting

How to sign URLs

How to generate signatures

Code examples

Integrations using an SDK

Integrations using URLs

Verify your implementation

Troubleshooting