Developer Documentation

1. Get your keys

Sign in, complete onboarding, then visit API Keys in the merchant dashboard to generate a test key. Every key has a key_id (public) and a secret shown only once at creation.

2. Authenticate

Pass your key on every request as an Authorization header:

Authorization: Basic base64(key_id:secret)
# or, more commonly:
X-Grosko-Key-Id: gpk_test_abc123
X-Grosko-Key-Secret: <plaintext-secret>

3. Create a payment (sandbox)

POST /api/public/v1/payments
Content-Type: application/json
X-Grosko-Key-Id: gpk_test_...
X-Grosko-Key-Secret: ...

{
  "amount": 49900,        // paise
  "currency": "INR",
  "method": "upi",
  "customer_email": "user@example.com",
  "customer_phone": "+919999999999",
  "metadata": { "order_id": "ord_1" }
}

Response returns a txn_ref (unique, prefixed with gp_txn_) and a simulated status. In sandbox, ~92% of requests are auto-marked succeeded and the rest failed.

4. Fetch a payment

GET /api/public/v1/payments/:txn_ref
X-Grosko-Key-Id: ...
X-Grosko-Key-Secret: ...

Errors

All errors are returned as JSON { "error": { "code", "message" } } with an appropriate HTTP status. 401 — missing or invalid credentials. 422 — validation error. 404 — not found.