Getting Started

Set up your GullyPay merchant account and process your first payment in under five minutes.

Installation

Install the GullyPay SDK for your language of choice.

SDK availability

The unified @gullypay/sdk package is in preview. Available on npm today: @gullypay/x402-sdk (x402 payments) and @gullypay/wallet-sdk (wallet + payment routing). The examples below show the target unified API.

Terminal

npm install @gullypay/sdk

Or use yarn / pnpm:

Terminal

yarn add @gullypay/sdk
# or
pnpm add @gullypay/sdk

For Python:

Terminal

pip install gullypay

Create an Account

Registration is open to everyone. Create a free account in the dashboard, or register through the API:

cURL

curl -X POST https://gullypay.xyz/api/auth/register \
-H "Content-Type: application/json" \
-d '{
  "email": "[email protected]",
  "password": "your-secure-password",
  "firstName": "Jane",
  "lastName": "Doe"
}'

The response includes a JWT access token (valid for 15 minutes) and a refresh token (valid for 7 days):

Response

{
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"refreshToken": "rt_a1b2c3d4e5f6...",
"user": {
  "id": "usr_abc123",
  "email": "[email protected]"
}
}

Authentication

GullyPay supports two authentication methods: JWT tokens for user sessions and API keys for server-to-server integrations.

JWT Tokens

Obtain a token pair by logging in:

cURL

curl -X POST https://gullypay.xyz/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]", "password": "your-password"}'

Include the access token in the Authorization header of every request:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

When the access token expires, use the refresh token to obtain a new pair:

Refresh Token

curl -X POST https://gullypay.xyz/api/auth/refresh \
-H "Content-Type: application/json" \
-d '{"refreshToken": "rt_a1b2c3d4e5f6..."}'

API Keys

For server-side integrations, create a scoped API key:

cURL

curl -X POST https://gullypay.xyz/api/auth/api-keys \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "name": "Production Server",
  "scopes": ["payments:write", "merchants:read", "orders:read"]
}'

Security

Store API keys securely in environment variables. Never commit them to source control or expose them in client-side code. GullyPay API keys start with rk_live_ (production) or rk_test_ (sandbox).

Use your API key in the Authorization header:

Authorization: Bearer rk_live_your_api_key

Create a Merchant

After authenticating, create a merchant account with an organization and default store:

create-merchant.ts

1import { GullyPay } from '@gullypay/sdk';
2
3const gullypay = new GullyPay({
4apiKey: 'rk_live_your_api_key',
5});
6
7const merchant = await gullypay.merchants.create({
8name: 'Acme Electronics',
9slug: 'acme-electronics',
10businessType: 'company',
11country: 'US',
12});
13
14console.log(merchant.id);        // "merch_xyz789"
15console.log(merchant.stores[0]); // Default store created automatically

Add a Store

Merchants can have multiple stores, each with its own domain, currency, and product catalog:

cURL

curl -X POST https://gullypay.xyz/api/merchants/merch_xyz789/stores \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "name": "Acme EU Store",
  "domain": "eu.acme-electronics.com",
  "currency": "EUR",
  "timezone": "Europe/London"
}'

Process Your First Payment

Create a payment intent to charge a customer:

first-payment.ts

1const payment = await gullypay.payments.create({
2amount: 2499,          // Amount in cents ($24.99)
3currency: 'USD',
4storeId: 'store_abc123',
5merchantId: 'merch_xyz789',
6customerEmail: '[email protected]',
7idempotencyKey: 'order_12345',  // Prevent duplicate charges
8});
9
10console.log(payment.id);     // "pi_a1b2c3"
11console.log(payment.status); // "requires_confirmation"
12
13// Confirm the payment
14const confirmed = await gullypay.payments.confirm(payment.id);
15console.log(confirmed.status); // "succeeded"

Info

Amounts are always in the smallest currency unit. For USD, 2499 means $24.99. For JPY (zero-decimal currency), 2499 means 2,499 yen.

Create a Checkout Session

For a full hosted checkout experience (similar to Stripe Checkout):

hosted-checkout.ts

1const session = await gullypay.checkout.createHosted({
2amount: 4999,
3currency: 'USD',
4storeId: 'store_abc123',
5merchantId: 'merch_xyz789',
6successUrl: 'https://yoursite.com/success?session={CHECKOUT_SESSION_ID}',
7cancelUrl: 'https://yoursite.com/cancel',
8});
9
10// Redirect the customer to the hosted checkout page
11console.log(session.url);
12// https://checkout.gullypay.xyz/cs_xyz789

Environment Setup

GullyPay provides separate sandbox and production environments.

	Sandbox	Production
Base URL	`https://gullypay.xyz/api`	`https://gullypay.xyz/api`
API Key prefix	`rk_test_`	`rk_live_`
Payments	Simulated (no real charges)	Real payment processing
Webhooks	Test events delivered	Live events delivered
Stripe	Uses Stripe test mode	Uses Stripe live mode

Start in Sandbox

Always develop and test against the sandbox environment first. Sandbox API keys never process real payments, so you can safely test your integration without financial risk.

Environment Variables

Set up your environment variables for local development:

.env

# GullyPay API Configuration
GULLYPAY_API_KEY=rk_test_your_sandbox_key
GULLYPAY_BASE_URL=https://gullypay.xyz/api

# Webhook signature verification
GULLYPAY_WEBHOOK_SECRET=whsec_your_webhook_secret

# Optional: Stripe keys for direct Stripe integration
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...

Next Steps

API Reference -- Explore the complete REST API with all endpoints
Webhooks -- Set up webhook listeners for real-time event notifications
x402 Protocol -- Monetize APIs with pay-per-request billing
SDKs -- Browse SDK documentation for TypeScript, Python, Go, and React Native