Grey Finance Business API (1.0)

• A registered business account with Grey Finance.
• Valid API credentials (see API Key Management below).
• An HTTPS-enabled environment for secure communication.

All API requests must be authenticated using an API key. The key should be included in the Authorization header of every request.

To generate your API key, log in to the dashboard:

1. Navigate to your Grey Finance business dashboard.
2. Go to Integrations › API keys and generate your key.

API keys consist of a Public Key and a Secret Key:

• Public Key — starts with gbpk_ (e.g. gbpk_abc123def456ghi789).
• Secret Key — starts with gbsk_ (e.g. gbsk_xyz789uvw456rst123).

Secure your API key

• Copy the generated key immediately — it will not be shown again.
• Store it securely in your application's environment variables.
• Never commit API keys to version control.

Include your API key in the Authorization header of every request:

curl -X GET "https://${baseUrl}/v1/grey-tags/johndoe" \
  -H "Authorization: Bearer gbsk_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Money-moving requests can be made safe to retry in two ways:

• Send an X-Idempotency-Key header, or
• Include a reference in the body of a payout (/v1/charge/payout).

When a request is retried with the same idempotency key — or the same reference for the same business — Grey returns the original response instead of performing the payment again, and sets X-Idempotent-Replayed: true on the replayed response. A duplicate that arrives while the first is still processing returns 409 Conflict.

Only successful (2xx) responses are replayed, so a payout that failed can be retried under the same reference. Reusing a reference with a different request body is rejected with 409 Conflict, so a genuine second payment is never silently swallowed. Replays are matched for 24 hours.

Currently we support three event types for webhooks:

Every webhook payload echoes your client_reference (when you supplied a reference on the request) alongside Grey's own transaction_reference, so you can match each event to your records. You can also look a transaction up at any time with GET /api/v1/transactions?client_reference=....

Every webhook payload includes a cryptographic signature in the X-Webhook-Signature header, computed with your webhook secret and the raw request body using HMAC-SHA256.

X-Webhook-Signature: sha256=abc123def456...

Verification steps

1. Get the signature from the X-Webhook-Signature header.
2. Compute an HMAC-SHA256 hash of the raw JSON body using your webhook secret.
3. Compare the two values — if they match the webhook is authentic.

package main

import (
  "crypto/hmac"
  "crypto/sha256"
  "encoding/hex"
  "io"
  "net/http"
  "strings"
)

const webhookSecret = "your-webhook-secret-here"

func validateSignature(payload []byte, signatureHeader, secret string) bool {
  if !strings.HasPrefix(signatureHeader, "sha256=") {
    return false
  }
  expectedSignature := strings.TrimPrefix(signatureHeader, "sha256=")
  h := hmac.New(sha256.New, []byte(secret))
  h.Write(payload)
  computedSignature := hex.EncodeToString(h.Sum(nil))
  return hmac.Equal([]byte(computedSignature), []byte(expectedSignature))
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
  body, err := io.ReadAll(r.Body)
  if err != nil {
    http.Error(w, "Failed to read request body", http.StatusBadRequest)
    return
  }
  defer r.Body.Close()

  signatureHeader := r.Header.Get("X-Webhook-Signature")
  if signatureHeader == "" {
    http.Error(w, "Missing signature header", http.StatusUnauthorized)
    return
  }

  if !validateSignature(body, signatureHeader, webhookSecret) {
    http.Error(w, "Invalid signature", http.StatusUnauthorized)
    return
  }

  w.WriteHeader(http.StatusOK)
  w.Write([]byte("Webhook received and validated successfully"))
}

Sample Webhook Payload

Headers:

Content-Type: application/json
X-Webhook-Event: transaction.success
X-Webhook-Delivery-ID: delivery-uuid-123
X-Webhook-Signature: sha256=abc123def456...
User-Agent: Grey-Webhook/1.0

Body:

{
  "event_type": "transaction.success",
  "transaction_id": "txn_abc123def456",
  "transaction_reference": "GREY7F3K2MQ9",
  "client_reference": "INV-2024-001",
  "business_id": "business-uuid",
  "amount": 1000.00,
  "source_currency": "USD",
  "destination_currency": "EUR",
  "status": "completed",
  "fees": 5.00,
  "fee_currency": "USD",
  "exchange_rate": 0.85,
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T11:30:00Z",
  "transaction_type": "p2p"
}

Look up supported payout methods, currency pairs, and Grey Tags.

Query business wallet balances.

Create P2P transfers, currency swaps, payouts, and check exchange rates.

Sandbox-only helpers for testing your integration (not available in production).

Manage API keys and webhooks for your integration.