Language

GetPaidly API

Business Plan

Access your business data programmatically. REST API for transactions, contacts, business summaries, and real-time webhooks.

Read-only + WebhooksJSON responsesAPI key auth30 req/min

Quick Start

Get up and running in 3 steps.

1

Get your API key

Send "api key" to GetPaidly on WhatsApp. You'll receive your unique API key instantly.

2

Make your first request

Try fetching your business summary:

bash
curl -H "x-api-key: YOUR_API_KEY" \
  https://getpaidly-development.up.railway.app/v1/summary
3

Explore endpoints

Browse the full endpoint reference below to access transactions, contacts, and more.

Authentication

All API requests require an x-api-key header.

cURL

bash
curl -H "x-api-key: YOUR_API_KEY" \
  https://getpaidly-development.up.railway.app/v1/summary

JavaScript (fetch)

javascript
const res = await fetch("https://getpaidly-development.up.railway.app/v1/summary", {
  headers: { "x-api-key": "YOUR_API_KEY" }
});
const data = await res.json();
console.log(data);

Python (requests)

python
import requests

res = requests.get(
    "https://getpaidly-development.up.railway.app/v1/summary",
    headers={"x-api-key": "YOUR_API_KEY"}
)
print(res.json())

Endpoints

Read-only data endpoints. Base URL: https://getpaidly-development.up.railway.app

Get a high-level overview of your business - outstanding, overdue, and collected totals.

Example Request

bash
curl -H "x-api-key: YOUR_API_KEY" \
  https://getpaidly-development.up.railway.app/v1/summary

Example Response

{
  "overdue": {
    "count": 3,
    "paise": 850000
  },
  "pending": {
    "count": 7,
    "paise": 1190000
  },
  "paid": {
    "count": 15,
    "paise": 2500000
  },
  "totalOutstandingPaise": 2040000,
  "contactCount": 10,
  "currencyCode": "INR"
}

List all transactions with filtering and pagination.

Parameters

NameTypeRequiredDescription
statusstringOptionalFilter by status: pending, overdue, paid
limitnumberOptionalMax results (default 50, max 200)
offsetnumberOptionalPagination offset (default 0)
contact_idstringOptionalFilter by contact UUID
startDatestringOptionalFilter from date (YYYY-MM-DD)
endDatestringOptionalFilter to date (YYYY-MM-DD)
searchstringOptionalSearch by contact name (fuzzy match)

Example Request

bash
curl -H "x-api-key: YOUR_API_KEY" \
  "https://getpaidly-development.up.railway.app/v1/transactions?status=pending&limit=10"

Example Response

{
  "data": [
    {
      "id": "uuid-here",
      "contactName": "Ramesh Steel",
      "contactPhone": "+919876543210",
      "amountPaise": 450000,
      "dueDate": "2026-03-20",
      "status": "pending",
      "paidAt": null,
      "createdAt": "2026-03-01T10: 30: 00Z",
      "paymentRef": null,
      "reminderCount": 2,
      "claimCount": 0
    }
  ],
  "total": 25,
  "limit": 50,
  "offset": 0
}

Get a single transaction by its UUID.

Parameters

NameTypeRequiredDescription
idstring (path)RequiredTransaction UUID

Example Request

bash
curl -H "x-api-key: YOUR_API_KEY" \
  https://getpaidly-development.up.railway.app/v1/transactions/TRANSACTION_ID

Example Response

{
  "id": "uuid-here",
  "contactName": "Ramesh Steel",
  "contactPhone": "+919876543210",
  "amountPaise": 450000,
  "dueDate": "2026-03-20",
  "status": "pending",
  "paidAt": null,
  "createdAt": "2026-03-01T10: 30: 00Z",
  "paymentRef": null,
  "reminderCount": 2,
  "claimCount": 0
}

List all contacts with search and pagination.

Parameters

NameTypeRequiredDescription
limitnumberOptionalMax results (default 50, max 200)
offsetnumberOptionalPagination offset (default 0)
searchstringOptionalSearch by name (fuzzy match)

Example Request

bash
curl -H "x-api-key: YOUR_API_KEY" \
  "https://getpaidly-development.up.railway.app/v1/contacts?search=ramesh"

Example Response

{
  "data": [
    {
      "id": "uuid-here",
      "name": "Ramesh Steel",
      "phone": "+919876543210",
      "outstandingPaise": 450000,
      "paymentScore": 78,
      "totalTransactions": 12,
      "createdAt": "2026-01-15T08: 00: 00Z"
    }
  ],
  "total": 10,
  "limit": 50,
  "offset": 0
}

Get a single contact with outstanding balance.

Parameters

NameTypeRequiredDescription
idstring (path)RequiredContact UUID

Example Request

bash
curl -H "x-api-key: YOUR_API_KEY" \
  https://getpaidly-development.up.railway.app/v1/contacts/CONTACT_ID

Example Response

{
  "id": "uuid-here",
  "name": "Ramesh Steel",
  "phone": "+919876543210",
  "outstandingPaise": 450000,
  "paymentScore": 78,
  "totalTransactions": 12,
  "createdAt": "2026-01-15T08: 00: 00Z"
}

Webhooks

Business Plan

Receive real-time notifications when events happen in your GetPaidly account. Register an HTTPS endpoint and we'll POST event payloads to it.

Webhook Endpoints

List all registered webhooks for your business.

Example Request

bash
curl -H "x-api-key: YOUR_API_KEY" \
  https://getpaidly-development.up.railway.app/v1/webhooks

Example Response

{
  "data": [
    {
      "id": "wh_uuid-here",
      "url": "https://example.com/webhook",
      "events": [
        "transaction.paid",
        "payment.received"
      ],
      "active": true,
      "createdAt": "2026-03-01T10: 30: 00Z"
    }
  ]
}

Create a new webhook. Returns a signing secret (shown only once - store it securely).

Parameters

NameTypeRequiredDescription
urlstringRequiredHTTPS endpoint URL to receive events
eventsstring[]RequiredArray of event types to subscribe to

Example Request

bash
curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/webhook","events":["transaction.paid"]}' \
  https://getpaidly-development.up.railway.app/v1/webhooks

Example Response

{
  "id": "wh_uuid-here",
  "url": "https://example.com/webhook",
  "events": [
    "transaction.paid",
    "payment.received"
  ],
  "secret": "whsec_abc123...",
  "active": true,
  "createdAt": "2026-03-10T14: 00: 00Z"
}

Delete a webhook by its ID. Stops all future event deliveries to this endpoint.

Parameters

NameTypeRequiredDescription
idstring (path)RequiredWebhook UUID

Example Request

bash
curl -X DELETE -H "x-api-key: YOUR_API_KEY" \
  https://getpaidly-development.up.railway.app/v1/webhooks/WEBHOOK_ID

Example Response

{
  "success": true,
  "message": "Webhook deleted"
}

Webhook Events

EventDescription
transaction.createdA new transaction (due) was added.
transaction.paidA transaction was marked as paid.
transaction.updatedA transaction was edited (amount, due date, etc.).
transaction.deletedA transaction was soft-deleted.
reminder.sentAn auto-reminder was sent to a buyer.
payment.receivedA payment was received and verified (UPI/Razorpay).

Payload Format

{
  "event": "transaction.paid",
  "timestamp": "2026-03-17T14: 30: 00Z",
  "data": {
    "id": "tx_uuid-here",
    "contactName": "Ramesh Steel",
    "amountPaise": 450000,
    "paidAt": "2026-03-17T14: 30: 00Z",
    "paymentRef": "UTR123456789"
  }
}

Security & Verification

Every webhook delivery includes an X-GetPaidly-Signature header containing an HMAC-SHA256 signature. Verify it by computing the HMAC of the raw request body using your webhook secret, then comparing with the header value.

javascript
// Node.js verification example
const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Try It Live

Paste your API key and send a real request. Responses come directly from the GetPaidly API.

Rate Limits

30 requests per minute

If you exceed the limit, you will receive a 429 status code. Wait 60 seconds before retrying.

Error Codes

Standard HTTP status codes are used to indicate success or failure.

StatusMeaningDescription
401UnauthorizedInvalid or missing API key.
403ForbiddenYour plan does not include API access. Upgrade to Business.
404Not FoundThe requested resource does not exist.
429Too Many RequestsRate limit exceeded. Wait and retry.
🛠️

Need a Custom API?

We're actively building new endpoints based on what our customers need. If you need write access, bulk operations, or any integration that would help your business - we'd love to hear from you.

Request on WhatsApp✉️ Email Us

Need help? Message us on WhatsApp

← Back to GetPaidly