Authentication

Every GoPay API request — payments (C2B) and transfers (B2C) alike — is authenticated with a detached Ed25519 signature sent in HTTP headers. Your private key stays on your servers; GoPay stores only the public verification key. This means a compromise of GoPay’s database can never be used to forge requests on your behalf.

API Keys

Create API keys in the merchant dashboard. Each key has:

A public key identifier — sent with every request in the X-Public-Key header
An Ed25519 key pair — you sign with the private half, GoPay verifies with the public half
Permissions — c2b (accept payments), b2c (make transfers), or both
Optional IP allowlist, per-merchant rate limit, and expiry

Two ways to get a key pair:

Server-generated (default)
Bring your own key

GoPay generates the key pair and returns the private key once, at creation time. Store it in a secrets manager immediately — GoPay does not keep a copy and cannot recover it.

If a private key is lost or leaked, rotate it from the dashboard. Rotation takes effect within seconds.

Required Headers

Header	Description
`X-Public-Key`	Your API key identifier
`X-Signature`	`ed25519=<base64>` — detached signature over the canonical string. Unpadded base64 preferred; padded and bare (no prefix) forms are accepted
`X-Timestamp`	Unix seconds, base-10. Rejected if more than 1 minute in the future or older than the freshness window (default 5 minutes)
`X-Request-ID`	Unique nonce per request. Each ID is accepted exactly once — resending one is rejected as a replay
`Idempotency-Key`	Optional, C2B only. Recommended when you retry on network errors
`Content-Type`	`application/json`

The Canonical String (v1)

The signature is computed over this string — lines joined with \n, no trailing newline:

v1
{METHOD}
{host}
{path}
{sorted_query}
{timestamp}
{request_id}
{body_sha256_hex}

Line	Rule
`v1`	Literal version prefix
`METHOD`	Uppercase HTTP method (`POST`)
`host`	Lowercase host, including port if non-default
`path`	Request path, e.g. `/api/v1/initiate-payment`
`sorted_query`	Query parameters sorted by key, then value, re-encoded (`k=v&k2=v2`); empty string if there is no query
`timestamp`	Same value as `X-Timestamp`
`request_id`	Same value as `X-Request-ID`
`body_sha256_hex`	Lowercase hex SHA-256 of the exact body bytes you send

Sign the canonical string with your Ed25519 private key and base64-encode the 64-byte result.

Because the host is part of the canonical string, a signature created for the sandbox cannot be replayed against production (and vice versa). Always sign with the exact host you send the request to.

Signing Helpers

Your private key is the base64 string shown once at key creation — it decodes to a 64-byte key (some libraries want only the first 32 bytes, the seed). These helpers return the exact headers to attach to any GoPay API request.

Node.js
Python
Go

// npm install tweetnacl
const crypto = require('crypto');
const nacl = require('tweetnacl');

// 64-byte Ed25519 private key, base64 (shown once at key creation)
const PRIVATE_KEY = Buffer.from(process.env.GOPAY_PRIVATE_KEY, 'base64');

function canonicalizeQuery(rawQuery) {
    if (!rawQuery) return '';
    const pairs = [...new URLSearchParams(rawQuery)];
    pairs.sort(([k1, v1], [k2, v2]) =>
        k1 === k2 ? (v1 < v2 ? -1 : v1 > v2 ? 1 : 0) : (k1 < k2 ? -1 : 1));
    return pairs
        .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
        .join('&');
}

// Returns the headers to attach to the request.
function signRequest(method, url, bodyBytes) {
    const u = new URL(url);
    const timestamp = Math.floor(Date.now() / 1000).toString();
    const requestId = crypto.randomUUID();
    const bodyHash = crypto.createHash('sha256').update(bodyBytes).digest('hex');

    const canonical = [
        'v1',
        method.toUpperCase(),
        u.host.toLowerCase(),
        u.pathname,
        canonicalizeQuery(u.search.slice(1)),
        timestamp,
        requestId,
        bodyHash,
    ].join('\n');

    const sig = nacl.sign.detached(Buffer.from(canonical, 'utf8'), PRIVATE_KEY);
    return {
        'X-Public-Key': process.env.GOPAY_PUBLIC_KEY,
        'X-Signature': 'ed25519=' + Buffer.from(sig).toString('base64').replace(/=+$/, ''),
        'X-Timestamp': timestamp,
        'X-Request-ID': requestId,
        'Content-Type': 'application/json',
    };
}

module.exports = { signRequest };

# pip install pynacl
import base64
import hashlib
import os
import time
import uuid
from urllib.parse import urlsplit, parse_qsl, quote

from nacl.signing import SigningKey

# 64-byte Ed25519 private key, base64 (shown once at key creation).
# PyNaCl takes the 32-byte seed, which is the first half.
_raw = base64.b64decode(os.environ["GOPAY_PRIVATE_KEY"])
SIGNING_KEY = SigningKey(_raw[:32])


def canonicalize_query(raw: str) -> str:
    if not raw:
        return ""
    pairs = sorted(parse_qsl(raw, keep_blank_values=True))
    return "&".join(f"{quote(k, safe='')}={quote(v, safe='')}" for k, v in pairs)


def sign_request(method: str, url: str, body: bytes) -> dict:
    """Returns the auth headers to attach to the request."""
    u = urlsplit(url)
    timestamp = str(int(time.time()))
    request_id = str(uuid.uuid4())
    body_hash = hashlib.sha256(body).hexdigest()

    canonical = "\n".join([
        "v1",
        method.upper(),
        u.netloc.lower(),
        u.path,
        canonicalize_query(u.query),
        timestamp,
        request_id,
        body_hash,
    ])

    sig = SIGNING_KEY.sign(canonical.encode("utf-8")).signature
    return {
        "X-Public-Key": os.environ["GOPAY_PUBLIC_KEY"],
        "X-Signature": "ed25519=" + base64.b64encode(sig).decode().rstrip("="),
        "X-Timestamp": timestamp,
        "X-Request-ID": request_id,
        "Content-Type": "application/json",
    }

package gopay

import (
    "crypto/ed25519"
    "crypto/sha256"
    "encoding/base64"
    "encoding/hex"
    "fmt"
    "net/url"
    "sort"
    "strings"
    "time"

    "github.com/google/uuid"
)

// SignRequest returns the auth headers for a GoPay API request.
// privateKeyB64 is the base64 64-byte Ed25519 private key shown once
// at key creation; publicKeyID is the X-Public-Key identifier.
func SignRequest(privateKeyB64, publicKeyID, method, rawURL string, body []byte) (map[string]string, error) {
    keyBytes, err := base64.StdEncoding.DecodeString(privateKeyB64)
    if err != nil {
        return nil, fmt.Errorf("decode private key: %w", err)
    }
    priv := ed25519.PrivateKey(keyBytes)

    u, err := url.Parse(rawURL)
    if err != nil {
        return nil, fmt.Errorf("parse url: %w", err)
    }

    timestamp := fmt.Sprintf("%d", time.Now().Unix())
    requestID := uuid.NewString()
    sum := sha256.Sum256(body)

    canonical := strings.Join([]string{
        "v1",
        strings.ToUpper(method),
        strings.ToLower(u.Host),
        u.Path,
        canonicalizeQuery(u.RawQuery),
        timestamp,
        requestID,
        hex.EncodeToString(sum[:]),
    }, "\n")

    sig := ed25519.Sign(priv, []byte(canonical))
    return map[string]string{
        "X-Public-Key": publicKeyID,
        "X-Signature":  "ed25519=" + base64.RawStdEncoding.EncodeToString(sig),
        "X-Timestamp":  timestamp,
        "X-Request-ID": requestID,
        "Content-Type": "application/json",
    }, nil
}

func canonicalizeQuery(raw string) string {
    if raw == "" {
        return ""
    }
    v, err := url.ParseQuery(raw)
    if err != nil {
        return raw
    }
    keys := make([]string, 0, len(v))
    for k := range v {
        keys = append(keys, k)
    }
    sort.Strings(keys)
    var b strings.Builder
    for i, k := range keys {
        vals := append([]string(nil), v[k]...)
        sort.Strings(vals)
        for j, val := range vals {
            if i > 0 || j > 0 {
                b.WriteByte('&')
            }
            b.WriteString(url.QueryEscape(k))
            b.WriteByte('=')
            b.WriteString(url.QueryEscape(val))
        }
    }
    return b.String()
}

What Else Is Checked

Beyond the signature, GoPay enforces per key:

Permission — the key must carry c2b for payments or b2c for transfers
IP allowlist — if configured, requests from other IPs are rejected
Replay protection — each X-Request-ID is accepted exactly once
Rate limit — a per-merchant request budget

Failed authentication returns a deliberately generic error — the response never reveals which check failed. See Errors for the full taxonomy.

Common Mistakes

Re-serializing the JSON body after signing — hash, sign, and send the same bytes. Serialize once.
Signing with the wrong host — sandbox and production signatures are not interchangeable; the host is part of the canonical string.
Reusing an X-Request-ID — each one is accepted exactly once; generate a fresh UUID per request (including retries).
Timestamps in milliseconds — the API expects unix seconds.
Signing with the wrong key half — some libraries want the 64-byte private key, others the 32-byte seed (its first half).

Verifying Webhooks

The same scheme runs in reverse for callbacks: GoPay signs every webhook with its gateway private key, and you verify with the gateway public key you receive at onboarding. See Webhooks for verification code.

Getting Started

Accept Payments

Make Transfers

Webhooks

Resources

Authentication

Authentication

API Keys

Required Headers

The Canonical String (v1)

Signing Helpers

What Else Is Checked

Common Mistakes

Verifying Webhooks

​Authentication

​API Keys

​Required Headers

​The Canonical String (v1)

​Signing Helpers

​What Else Is Checked

​Common Mistakes

​Verifying Webhooks

Authentication

API Keys

Required Headers

The Canonical String (v1)

Signing Helpers

What Else Is Checked

Common Mistakes

Verifying Webhooks