v1.0

API Reference

Build integrations with the GAdsfy REST API. Accept international payments, query transactions, and manage your product catalog programmatically.

Authentication

All API requests must include your secret API key in the Authorization header. You can generate and manage keys from the GAdsfy Dashboard under Settings → API Keys.

Include this header in every request:

Authorization: Bearer gads_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep your keys secret

Never expose your API keys in client-side code, public repositories, or browser requests. Always make API calls from your server.

Base URL

All API endpoints are relative to the following base URL.

https://api.gadsfy.com/v1

Rate Limiting

To ensure fair usage, API requests are subject to rate limits.

Plan	Limit	Window
Standard	100 requests	per minute
Enterprise	1,000 requests	per minute

Rate limit status is returned in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Error Codes

The API returns standard HTTP error codes along with a JSON body containing the error details.

Code	Status	Description
400	Bad Request	The request body is malformed or missing required fields.
401	Unauthorized	Invalid or missing API key.
404	Not Found	The requested resource does not exist.
429	Too Many Requests	Rate limit exceeded. Retry after the period specified in headers.
500	Internal Server Error	An unexpected error occurred on our end. Contact support if it persists.

Error response shapejson

{
  "error": {
    "code": "invalid_request",
    "message": "The field 'amount' is required.",
    "status": 400
  }
}

Endpoints

Core API endpoints for payments, transactions, and products.

Create Checkout Session

Creates a new payment checkout session. Returns a URL where the customer completes payment.

POST/v1/checkouts

Request Body

Parameter	Type	Description
`product_id`required	string	The ID of the product to purchase.
`success_url`required	string	URL to redirect the customer after a successful payment.
`upsell_url`	string	URL shown as a special offer card on the receipt page after purchase.
`customer_email`	string	Pre-fill the customer's email address on the checkout form.
`metadata`	object	Arbitrary key-value pairs attached to the checkout session.
`currency`	string	ISO 4217 currency code (default: `USD`). Supported: USD, EUR, GBP, ZAR.

Examples

Create a checkout sessioncurl

curl -X POST https://api.gadsfy.com/v1/checkouts \
  -H "Authorization: Bearer gads_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_abc123",
    "success_url": "https://yoursite.com/success",
    "upsell_url": "https://yoursite.com/special-offer",
    "customer_email": "buyer@example.com",
    "currency": "USD",
    "metadata": {
      "order_ref": "ORD-9281"
    }
  }'

Create a checkout sessionjavascript

const response = await fetch("https://api.gadsfy.com/v1/checkouts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer gads_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    product_id: "prod_abc123",
    success_url: "https://yoursite.com/success",
    upsell_url: "https://yoursite.com/special-offer",
    customer_email: "buyer@example.com",
    currency: "USD",
    metadata: { order_ref: "ORD-9281" },
  }),
});

const session = await response.json();
console.log(session.checkout_url);

Create a checkout sessionpython

import requests

response = requests.post(
    "https://api.gadsfy.com/v1/checkouts",
    headers={
        "Authorization": "Bearer gads_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
    json={
        "product_id": "prod_abc123",
        "success_url": "https://yoursite.com/success",
        "upsell_url": "https://yoursite.com/special-offer",
        "customer_email": "buyer@example.com",
        "currency": "USD",
        "metadata": {"order_ref": "ORD-9281"},
    },
)

session = response.json()
print(session["checkout_url"])

Response

201 Createdjson

{
  "id": "cs_xK7mNpQ2wL9r",
  "object": "checkout_session",
  "status": "pending",
  "checkout_url": "https://pay.gadsfy.com/cs_xK7mNpQ2wL9r",
  "product_id": "prod_abc123",
  "currency": "USD",
  "amount": 4900,
  "customer_email": "buyer@example.com",
  "metadata": {
    "order_ref": "ORD-9281"
  },
  "created_at": "2026-04-05T10:30:00Z",
  "expires_at": "2026-04-05T11:30:00Z"
}

Get Transaction

Retrieve the details and current status of a specific transaction.

GET/v1/transactions/{id}

Path Parameters

Parameter	Type	Description
`id`required	string	The unique transaction identifier (e.g. `txn_rS8qYm3jN`).

Examples

Query a transactioncurl

curl https://api.gadsfy.com/v1/transactions/txn_rS8qYm3jN \
  -H "Authorization: Bearer gads_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Query a transactionjavascript

const response = await fetch(
  "https://api.gadsfy.com/v1/transactions/txn_rS8qYm3jN",
  {
    headers: {
      "Authorization": "Bearer gads_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    },
  }
);

const transaction = await response.json();
console.log(transaction.status); // "approved"

Query a transactionpython

import requests

response = requests.get(
    "https://api.gadsfy.com/v1/transactions/txn_rS8qYm3jN",
    headers={
        "Authorization": "Bearer gads_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    },
)

transaction = response.json()
print(transaction["status"])  # "approved"

Response

200 OKjson

{
  "id": "txn_rS8qYm3jN",
  "object": "transaction",
  "status": "approved",
  "amount": 4900,
  "currency": "USD",
  "product_id": "prod_abc123",
  "customer": {
    "email": "buyer@example.com",
    "name": "John Doe",
    "country": "ZA"
  },
  "payment_method": "card",
  "checkout_session_id": "cs_xK7mNpQ2wL9r",
  "metadata": {
    "order_ref": "ORD-9281"
  },
  "created_at": "2026-04-05T10:32:15Z",
  "updated_at": "2026-04-05T10:32:18Z"
}

List Products

Retrieve a paginated list of products on your GAdsfy account.

GET/v1/products

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: `1`).
`limit`	integer	Results per page, max 100 (default: `20`).
`status`	string	Filter by status: `active`, `draft`, or `archived`.

Examples

List productscurl

curl "https://api.gadsfy.com/v1/products?page=1&limit=10&status=active" \
  -H "Authorization: Bearer gads_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

List productsjavascript

const response = await fetch(
  "https://api.gadsfy.com/v1/products?page=1&limit=10&status=active",
  {
    headers: {
      "Authorization": "Bearer gads_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    },
  }
);

const { data, pagination } = await response.json();
console.log(`Found ${pagination.total} products`);

List productspython

import requests

response = requests.get(
    "https://api.gadsfy.com/v1/products",
    headers={
        "Authorization": "Bearer gads_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    },
    params={"page": 1, "limit": 10, "status": "active"},
)

result = response.json()
print(f"Found {result['pagination']['total']} products")

Response

200 OKjson

{
  "object": "list",
  "data": [
    {
      "id": "prod_abc123",
      "name": "Digital Marketing Masterclass",
      "description": "Complete VSL funnel training for African markets",
      "price": 4900,
      "currency": "USD",
      "status": "active",
      "checkout_url": "https://pay.gadsfy.com/prod_abc123",
      "created_at": "2026-03-15T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "total_pages": 1
  }
}

Next Steps

Webhooks →

Receive real-time notifications for payment events.