Signed Requests

Some API requests require a cryptographic signature to authorize the action. This applies to requests that move funds — specifically, capturing and refunding payments in two-step mode.

Why Are Some Requests Signed?

Your API key authenticates who you are, but it is not enough to move funds. Captures and refunds transfer stablecoins between wallets, so they require proof that you — the merchant — explicitly authorized the action.

This is done with a signing key: a separate cryptographic key-pair that you control. You sign the request body with your private key and include the signature in the X-Signature header. The API verifies the signature before executing the action.

Setting Up Your Signing Key

1. Generate a Key-Pair

Generate an ECDSA key-pair using any of the following tools:

openssl ecparam -name secp256k1 -genkey -noout -out signing-key.pem && openssl ec -in signing-key.pem -pubout -out signing-key.pub.pem

node -e "const c=require('crypto'),{privateKey,publicKey}=c.generateKeyPairSync('ec',{namedCurve:'secp256k1',publicKeyEncoding:{type:'spki',format:'pem'},privateKeyEncoding:{type:'pkcs8',format:'pem'}});require('fs').writeFileSync('signing-key.pem',privateKey);require('fs').writeFileSync('signing-key.pub.pem',publicKey);console.log('Keys saved to signing-key.pem and signing-key.pub.pem')"

python3 -c "from cryptography.hazmat.primitives.asymmetric import ec; from cryptography.hazmat.primitives import serialization; k=ec.generate_private_key(ec.SECP256K1()); open('signing-key.pem','wb').write(k.private_bytes(serialization.Encoding.PEM,serialization.PrivateFormat.PKCS8,serialization.NoEncryption())); open('signing-key.pub.pem','wb').write(k.public_key().public_bytes(serialization.Encoding.PEM,serialization.PublicFormat.SubjectPublicKeyInfo)); print('Keys saved to signing-key.pem and signing-key.pub.pem')"

2. Register Your Public Key

Send your public key to your account manager. Once received, we will configure your account for two-step payments.

Signing a Request

When making a capture or refund request, sign the JSON-serialized request body using ECDSA with your private key and include the signature in the X-Signature header.

Request Body

The request body is a JSON object containing the action and payment ID:

Capture:

{
  "action": "capture",
  "payment_id": "pay_0987654321fedcba"
}

Refund:

{
  "action": "refund",
  "payment_id": "pay_0987654321fedcba"
}

Creating the Signature

import crypto from 'crypto';
 
function signRequest(body, privateKey) {
  const payload = JSON.stringify(body);
  const sign = crypto.createSign('SHA256');
  sign.update(payload);
  return sign.sign(privateKey, 'hex');
}
 
// Example: sign a capture request
const body = {
  action: 'capture',
  payment_id: 'pay_0987654321fedcba',
};
 
const signature = signRequest(body, process.env.SIGNING_PRIVATE_KEY);
 
// Send to the API
const response = await fetch('https://checkout.exodus.com/payments/pay_0987654321fedcba/capture', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
    'X-Signature': signature,
  },
  body: JSON.stringify(body),
});

Security Best Practices

1. Keep your private key secret — store it in a secure environment (e.g., environment variables, secrets manager). Never expose it in client-side code or version control.
2. Separate from API key — your signing key and API key serve different purposes. Compromising one does not compromise the other.
3. Rotate if compromised — if you suspect your signing private key has been compromised, contact your account manager immediately to register a new public key.