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://api.getpaidly.com/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://api.getpaidly.com/v1/summary

JavaScript (fetch)

javascript
const res = await fetch("https://api.getpaidly.com/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://api.getpaidly.com/v1/summary",
    headers={"x-api-key": "YOUR_API_KEY"}
)
print(res.json())

Endpoints

Read-only data endpoints. Base URL: https://api.getpaidly.com

The business this API key belongs to. Use it to confirm the key and read your currency, language and timezone.

Example Request

bash
curl -H "x-api-key: YOUR_API_KEY" \
  https://api.getpaidly.com/v1/me

Example Response

{
  "data": {
    "id": "6f0eā€¦9d21",
    "name": "Sharma Exports",
    "phone": "919876500000",
    "plan": "business",
    "plan_expires_at": "2027-01-01T00: 00: 00.000Z",
    "currency": "INR",
    "language": "en",
    "timezone": "Asia/Kolkata",
    "country": "IN",
    "created_at": "2026-03-16T18: 30: 00.000Z"
  }
}

Outstanding, overdue and collected totals - the same numbers your dashboard shows.

Example Request

bash
curl -H "x-api-key: YOUR_API_KEY" \
  https://api.getpaidly.com/v1/summary
overdue = status overdue, or pending with a past due date. outstanding = pending + overdue.

Example Response

{
  "data": {
    "currency": "INR",
    "overdue": {
      "count": 3,
      "paise": 850000
    },
    "pending": {
      "count": 7,
      "paise": 1190000
    },
    "paid": {
      "count": 15,
      "paise": 2500000
    },
    "paid_this_month_paise": 640000,
    "total_outstanding_paise": 2040000,
    "contact_count": 10
  }
}

List receivables with filtering and pagination. Newest due dates first.

Parameters

NameTypeRequiredDescription
statusstringOptionalpending | overdue | outstanding | paid
contact_iduuidOptionalOnly this contact
sinceISO 8601OptionalOnly rows updated on or after this time - use it to sync incrementally
limitnumberOptionalDefault 50, max 200
offsetnumberOptionalDefault 0

Example Request

bash
curl -H "x-api-key: YOUR_API_KEY" \
  https://api.getpaidly.com/v1/transactions?status=overdue&limit=10

Example Response

{
  "data": [
    {
      "id": "3f2c9c9e-8f4a-4a1e-9b1e-0f6a3c2b7d10",
      "contact_id": "a1b2c3d4-0000-4000-8000-000000000001",
      "contact_name": "Ramesh Steel",
      "contact_phone": "919876543210",
      "amount_paise": 450000,
      "currency": "INR",
      "status": "pending",
      "direction": "receivable",
      "due_date": "2026-10-20T00: 00: 00.000Z",
      "paid_at": null,
      "utr": null,
      "payment_method": null,
      "invoice_number": "INV-42",
      "notes": "Steel rods, 20 pcs",
      "recurrence": null,
      "reminder_count": 2,
      "pay_page_url": "https://getpaidly.com/pay/7c1fā€¦e9a2",
      "created_at": "2026-09-15T10: 30: 00.000Z",
      "updated_at": "2026-09-15T10: 30: 00.000Z"
    }
  ],
  "total": 25,
  "limit": 50,
  "offset": 0,
  "hasMore": false
}

One transaction, including its hosted pay page link you can share with the buyer.

Parameters

NameTypeRequiredDescription
iduuidRequiredTransaction id (path)

Example Request

bash
curl -H "x-api-key: YOUR_API_KEY" \
  https://api.getpaidly.com/v1/transactions/TRANSACTION_ID

Example Response

{
  "data": {
    "id": "3f2c9c9e-8f4a-4a1e-9b1e-0f6a3c2b7d10",
    "contact_id": "a1b2c3d4-0000-4000-8000-000000000001",
    "contact_name": "Ramesh Steel",
    "contact_phone": "919876543210",
    "amount_paise": 450000,
    "currency": "INR",
    "status": "pending",
    "direction": "receivable",
    "due_date": "2026-10-20T00: 00: 00.000Z",
    "paid_at": null,
    "utr": null,
    "payment_method": null,
    "invoice_number": "INV-42",
    "notes": "Steel rods, 20 pcs",
    "recurrence": null,
    "reminder_count": 2,
    "pay_page_url": "https://getpaidly.com/pay/7c1fā€¦e9a2",
    "created_at": "2026-09-15T10: 30: 00.000Z",
    "updated_at": "2026-09-15T10: 30: 00.000Z"
  }
}

Create a due. Pass an existing contact_id, or contact_name (+ optional contact_phone) to find-or-create the contact by name. Reminders are scheduled automatically for the due date.

Parameters

NameTypeRequiredDescription
amount_paiseintegerRequiredAmount in the smallest unit (paise). Must be a whole number > 0.
due_dateYYYY-MM-DDRequiredDue date
contact_iduuidOptionalExisting contact. Either this or contact_name.
contact_namestringOptionalName is identity: an existing contact with the same name is reused
contact_phonestringOptionalWhatsApp number; needed for reminders. Any format, normalised for you.
notesstringOptionalUp to 500 chars
invoice_numberstringOptionalYour own reference, up to 60 chars
Idempotency-KeyheaderOptionalRetry-safe: the same key within 24h returns the original transaction instead of creating a duplicate

Request Body

{
  "contact_name": "Ramesh Steel",
  "contact_phone": "9876543210",
  "amount_paise": 450000,
  "due_date": "2026-10-20",
  "notes": "Steel rods, 20 pcs",
  "invoice_number": "INV-42"
}

Example Request

bash
curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{"contact_name":"Ramesh Steel","contact_phone":"9876543210","amount_paise":450000,"due_date":"2026-10-20"}' \
  https://api.getpaidly.com/v1/transactions

Example Response

{
  "data": {
    "id": "3f2c9c9e-8f4a-4a1e-9b1e-0f6a3c2b7d10",
    "contact_id": "a1b2c3d4-0000-4000-8000-000000000001",
    "contact_name": "Ramesh Steel",
    "contact_phone": "919876543210",
    "amount_paise": 450000,
    "currency": "INR",
    "status": "pending",
    "direction": "receivable",
    "due_date": "2026-10-20T00: 00: 00.000Z",
    "paid_at": null,
    "utr": null,
    "payment_method": null,
    "invoice_number": "INV-42",
    "notes": "Steel rods, 20 pcs",
    "recurrence": null,
    "reminder_count": 2,
    "pay_page_url": "https://getpaidly.com/pay/7c1fā€¦e9a2",
    "created_at": "2026-09-15T10: 30: 00.000Z",
    "updated_at": "2026-09-15T10: 30: 00.000Z"
  },
  "contact_created": false
}

Record that a due was paid (cash, bank transfer, or a UPI payment you received elsewhere). Updates the contact balance and fires transaction.paid.

Parameters

NameTypeRequiredDescription
iduuidRequiredTransaction id (path)
utrstringOptionalUPI/bank reference, up to 60 chars
payment_methodstringOptionalupi | cash | bank_transfer | card | other (default api)

Request Body

{
  "utr": "426512345678",
  "payment_method": "upi"
}

Example Request

bash
curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"utr":"426512345678","payment_method":"upi"}' \
  https://api.getpaidly.com/v1/transactions/TRANSACTION_ID/mark-paid
Returns 409 if the transaction is already paid.

Example Response

{
  "data": {
    "id": "3f2c9c9e-8f4a-4a1e-9b1e-0f6a3c2b7d10",
    "contact_id": "a1b2c3d4-0000-4000-8000-000000000001",
    "contact_name": "Ramesh Steel",
    "contact_phone": "919876543210",
    "amount_paise": 450000,
    "currency": "INR",
    "status": "paid",
    "direction": "receivable",
    "due_date": "2026-10-20T00: 00: 00.000Z",
    "paid_at": "2026-09-15T12: 00: 00.000Z",
    "utr": "426512345678",
    "payment_method": "upi",
    "invoice_number": "INV-42",
    "notes": "Steel rods, 20 pcs",
    "recurrence": null,
    "reminder_count": 2,
    "pay_page_url": "https://getpaidly.com/pay/7c1fā€¦e9a2",
    "created_at": "2026-09-15T10: 30: 00.000Z",
    "updated_at": "2026-09-15T10: 30: 00.000Z"
  }
}

Send a WhatsApp reminder for this due right now. Respects the same protections as automatic reminders (opt-out, 24h cooldown, weekly cap, quiet hours) - the response tells you whether it went and why not.

Parameters

NameTypeRequiredDescription
iduuidRequiredTransaction id (path)
templatestringOptionalreminder_upcoming | reminder_due_today | reminder_overdue_week | reminder_final. Chosen automatically from the due date if omitted.

Request Body

{
  "template": "reminder_overdue_week"
}

Example Request

bash
curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://api.getpaidly.com/v1/transactions/TRANSACTION_ID/remind
reason when not sent: opted_out | no_phone | paused | too_soon | max_reached | quiet_hours

Example Response

{
  "data": {
    "sent": true,
    "reason": null,
    "template": "reminder_overdue_week"
  }
}

List contacts with search and pagination.

Parameters

NameTypeRequiredDescription
searchstringOptionalName contains (min 2 chars)
phonestringOptionalPhone ends with these digits (min 6)
limitnumberOptionalDefault 50, max 200
offsetnumberOptionalDefault 0

Example Request

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

Example Response

{
  "data": [
    {
      "id": "a1b2c3d4-0000-4000-8000-000000000001",
      "name": "Ramesh Steel",
      "phone": "919876543210",
      "risk_flag": "normal",
      "created_at": "2026-08-01T08: 00: 00.000Z",
      "updated_at": "2026-09-15T10: 30: 00.000Z"
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0,
  "hasMore": false
}

One contact with balances and payment score.

Parameters

NameTypeRequiredDescription
iduuidRequiredContact id (path)

Example Request

bash
curl -H "x-api-key: YOUR_API_KEY" \
  https://api.getpaidly.com/v1/contacts/CONTACT_ID

Example Response

{
  "data": {
    "id": "a1b2c3d4-0000-4000-8000-000000000001",
    "name": "Ramesh Steel",
    "phone": "919876543210",
    "risk_flag": "normal",
    "created_at": "2026-08-01T08: 00: 00.000Z",
    "updated_at": "2026-09-15T10: 30: 00.000Z",
    "payment_score": 82,
    "outstanding_paise": 450000,
    "pending_count": 1,
    "overdue_count": 0,
    "total_transactions": 9
  }
}

Create a contact. Name is identity within your business: if a contact with the same name exists it is returned with created: false.

Parameters

NameTypeRequiredDescription
namestringRequired2-120 chars
phonestringOptionalWhatsApp number in any format
Idempotency-KeyheaderOptionalRetry-safe for 24h

Request Body

{
  "name": "Ramesh Steel",
  "phone": "9876543210"
}

Example Request

bash
curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ramesh Steel","phone":"9876543210"}' \
  https://api.getpaidly.com/v1/contacts

Example Response

{
  "data": {
    "id": "a1b2c3d4-0000-4000-8000-000000000001",
    "name": "Ramesh Steel",
    "phone": "919876543210",
    "risk_flag": "normal",
    "created_at": "2026-08-01T08: 00: 00.000Z",
    "updated_at": "2026-09-15T10: 30: 00.000Z"
  },
  "created": true
}

Update a contact's name and/or phone. Send phone: null to clear it.

Parameters

NameTypeRequiredDescription
iduuidRequiredContact id (path)
namestringOptional2-120 chars
phonestring | nullOptionalNew number, or null to remove

Request Body

{
  "phone": "9876500001"
}

Example Request

bash
curl -X PATCH -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"9876500001"}' \
  https://api.getpaidly.com/v1/contacts/CONTACT_ID

Example Response

{
  "data": {
    "id": "a1b2c3d4-0000-4000-8000-000000000001",
    "name": "Ramesh Steel",
    "phone": "919876500001",
    "risk_flag": "normal",
    "created_at": "2026-08-01T08: 00: 00.000Z",
    "updated_at": "2026-09-15T10: 30: 00.000Z"
  }
}

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 your webhook endpoints. Secrets are never returned here.

Example Request

bash
curl -H "x-api-key: YOUR_API_KEY" \
  https://api.getpaidly.com/v1/webhooks

Example Response

{
  "data": [
    {
      "id": "wh_ā€¦",
      "url": "https://example.com/webhook",
      "events": [
        "transaction.paid"
      ],
      "active": true,
      "created_at": "2026-09-15T10: 00: 00.000Z",
      "last_triggered_at": null,
      "failure_count": 0
    }
  ],
  "events": [
    "transaction.created",
    "transaction.paid",
    "transaction.deleted",
    "transaction.updated",
    "contact.created",
    "reminder.sent",
    "payment.received"
  ]
}

Register an HTTPS endpoint. The signing secret is returned exactly once - store it.

Parameters

NameTypeRequiredDescription
urlstringRequiredMust start with https://
eventsstring[]RequiredOne or more of the events listed below

Request Body

{
  "url": "https://example.com/webhook",
  "events": [
    "transaction.paid",
    "payment.received"
  ]
}

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://api.getpaidly.com/v1/webhooks

Example Response

{
  "data": {
    "id": "wh_ā€¦",
    "url": "https://example.com/webhook",
    "events": [
      "transaction.paid",
      "payment.received"
    ],
    "active": true,
    "created_at": "2026-09-15T10: 00: 00.000Z",
    "secret": "shown-once-64-hex-chars"
  }
}

Deliver a signed sample event to this endpoint so you can verify your handler without waiting for real activity.

Parameters

NameTypeRequiredDescription
iduuidRequiredWebhook id (path)

Example Request

bash
curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://api.getpaidly.com/v1/webhooks/WEBHOOK_ID/test

Example Response

{
  "data": {
    "delivered": true,
    "event": "transaction.paid"
  }
}

Delivery log for one endpoint - each attempt with status (pending / delivered / failed), response code, error and retry schedule. Newest first.

Parameters

NameTypeRequiredDescription
iduuidRequiredWebhook id (path)
limitintegerOptional1-100, default 50

Example Request

bash
curl -H "x-api-key: YOUR_API_KEY" \
  https://api.getpaidly.com/v1/webhooks/WEBHOOK_ID/deliveries

Example Response

{
  "data": [
    {
      "id": "...",
      "event": "transaction.paid",
      "status": "delivered",
      "attempts": 1,
      "response_status": 200,
      "delivered_at": "2026-09-16T10: 00: 00.000Z"
    }
  ]
}

Re-queue a logged delivery to be sent again immediately (the redeliver button). Failed deliveries are also retried automatically with backoff: 1m, 5m, 30m, 2h, 6h (6 attempts total).

Parameters

NameTypeRequiredDescription
iduuidRequiredWebhook id (path)
deliveryIduuidRequiredDelivery id (path)

Example Request

bash
curl -X POST -H "x-api-key: YOUR_API_KEY" \
  https://api.getpaidly.com/v1/webhooks/WEBHOOK_ID/deliveries/DELIVERY_ID/redeliver

Example Response

{
  "data": {
    "requeued": true
  }
}

Remove a webhook endpoint.

Parameters

NameTypeRequiredDescription
iduuidRequiredWebhook id (path)

Example Request

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

Example Response

{
  "deleted": true
}

Webhook Events

EventDescription
transaction.createdA due was added (WhatsApp, dashboard, import or API).
transaction.updatedAmount, due date or notes changed.
transaction.paidA due was marked paid.
transaction.deletedA due was removed.
payment.receivedA buyer paid through the hosted pay page or a payment link.
reminder.sentA WhatsApp reminder went out for a due.
contact.createdA new contact was added.

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
400Bad RequestA field is missing or invalid. The error message says which.
401UnauthorizedInvalid or missing API key.
403ForbiddenYour plan does not include API access. Upgrade to Business.
404Not FoundThe resource does not exist or belongs to another business.
409ConflictThe action does not apply to the current state, e.g. marking an already-paid due as paid.
422UnprocessableThe request was valid but could not be completed, e.g. the transaction could not be created.
429Too Many RequestsRate limit exceeded (30 requests per minute). 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