API Reference

The NahuPay REST API accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

Base URL

https://api.nahupay.com/v1

Authentication

All requests require an Authorization header carrying your secret key as a Bearer token.

curl https://api.nahupay.com/v1/payments \
  -H "Authorization: Bearer test_sk_abc123"

Keys prefixed with test_ operate in sandbox — no real money moves. Keys prefixed with live_ process real payments.

Content type

POST and PATCH requests must include Content-Type: application/json and a JSON body. GET requests use query parameters.

Errors

NahuPay uses conventional HTTP status codes. The response body always includes an error object:

{
  "error": {
    "code":    "invalid_amount",
    "message": "Amount must be a positive integer in ETB cents.",
    "param":   "amount"
  }
}

Status	Meaning
`200`	Success
`201`	Created
`400`	Bad request — check error.param for which field is invalid
`401`	Unauthorised — missing or invalid API key
`404`	Not found — resource does not exist or belongs to another account
`409`	Conflict — e.g. idempotency key reused with different params
`429`	Rate limit exceeded — wait for Retry-After seconds
`500`	Server error — try again; contact support if it persists

Pagination

List endpoints use cursor-based pagination. Pass ?after=pay_xyz to get the page after a given ID. The response includes a has_more boolean and a data array.

GET /v1/payments?limit=20&after=pay_abc
{
  "data": [...],
  "has_more": true,
  "next_cursor": "pay_def"
}