Payments API | Genaya API Reference

Money

Payments

Payment history, and recording payments taken outside Genaya.

GET/payments

List payments

Returns the organization's payment history. Stripe identifiers are never exposed. Requires scope: payments:read.

Parameters

Query

invoiceId

string

companyId

string

Only payments assigned to this company. A company that is not one of your organization's returns an empty list.

method

string

status

string

provider

string

Response 200

No fields.

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/payments \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "",
      "object": "payment",
      "invoiceId": "",
      "companyId": "cmp_9aF2",
      "companyName": "Avery HVAC - North",
      "amount": 0,
      "currency": "",
      "method": "",
      "provider": "",
      "status": "",
      "fee": 0,
      "serviceFee": 0,
      "net": 0,
      "cardBrand": "",
      "last4": "",
      "clientName": "",
      "clientEmail": "",
      "note": "",
      "paidOn": "",
      "createdAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": ""
}

POST/payments

Record an offline payment

Records a payment that was taken OUTSIDE Genaya - cash on site, a mailed check, a bank transfer - against an invoice, and recalculates that invoice's paid amount and balance. Requires scope: payments:write. This endpoint cannot charge a card, and that is deliberate. An API key is an organization-wide bearer credential with no second factor and no cardholder present. If it could charge a stored card, a single leaked key would be enough to run charges against your customers. Card payments stay on the paths that have a human or a cardholder in the loop: the app, the client portal, and Genaya payment links. Passing a card method here is rejected with `card_payments_not_supported`. Send an Idempotency-Key. Without one, a retry after a network timeout records the payment twice and the invoice shows as overpaid.

Request body

FieldTypeDescription

invoiceIdrequired

string

The invoice this payment settles. Must belong to your organization.

amountrequired

number

Amount received, in the invoice's currency. Rounded to cents.

methodrequired

enumCash | Check | Bank Transfer | Other

companyId

string

The company this payment is assigned to. Must be one of your organization's companies (GET /v1/companies); any other value is rejected with `invalid_companyId`. When omitted, the invoice's company is used, then your only company when you have exactly one; otherwise the payment carries no company.

paidOn

string <date-time>

When the payment was actually received. Defaults to now.

note

string

Response 201

FieldTypeDescription

id

string

object

string

invoiceId

string

nullable

companyId

string

Identifier of the company that collected this payment (one of your organization's companies). Null when the payment is not assigned to a company.nullable

companyName

string

Display name of the collecting company. Null when unset.nullable

amount

number

nullable

currency

string

method

string

nullable

provider

string

genaya_pay when Genaya processed it, manual when it was recorded from elsewhere.nullable

status

string

nullable

fee

number

nullable

serviceFee

number

nullable

net

number

nullable

cardBrand

string

nullable

last4

string

nullable

clientName

string

nullable

clientEmail

string

nullable

note

string

paidOn

string

nullable

createdAt

string <date-time>

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

409Idempotency-Key reused with a different body

429Rate limited

500Unexpected server error

curl -X POST https://api.genaya.com/v1/payments \
  -H "Authorization: Bearer gny_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "invoiceId": "",
  "amount": 0,
  "method": "Cash",
  "companyId": "cmp_9aF2",
  "paidOn": "2026-01-15T09:30:00.000Z",
  "note": ""
}'

Example response

{
  "data": {
    "id": "",
    "object": "payment",
    "invoiceId": "",
    "companyId": "cmp_9aF2",
    "companyName": "Avery HVAC - North",
    "amount": 0,
    "currency": "",
    "method": "",
    "provider": "",
    "status": "",
    "fee": 0,
    "serviceFee": 0,
    "net": 0,
    "cardBrand": "",
    "last4": "",
    "clientName": "",
    "clientEmail": "",
    "note": "",
    "paidOn": "",
    "createdAt": "2026-01-15T09:30:00.000Z"
  }
}

GET/payments/{id}

Retrieve a payment

Returns a single payment by id. A payment belonging to another organization returns 404 rather than 403. Requires scope: payments:read.

Parameters

Path

idrequired

string

Response 200

FieldTypeDescription

id

string

object

string

invoiceId

string

nullable

companyId

string

Identifier of the company that collected this payment (one of your organization's companies). Null when the payment is not assigned to a company.nullable

companyName

string

Display name of the collecting company. Null when unset.nullable

amount

number

nullable

currency

string

method

string

nullable

provider

string

genaya_pay when Genaya processed it, manual when it was recorded from elsewhere.nullable

status

string

nullable

fee

number

nullable

serviceFee

number

nullable

net

number

nullable

cardBrand

string

nullable

last4

string

nullable

clientName

string

nullable

clientEmail

string

nullable

note

string

paidOn

string

nullable

createdAt

string <date-time>

Errors

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/payments/{id} \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "data": {
    "id": "",
    "object": "payment",
    "invoiceId": "",
    "companyId": "cmp_9aF2",
    "companyName": "Avery HVAC - North",
    "amount": 0,
    "currency": "",
    "method": "",
    "provider": "",
    "status": "",
    "fee": 0,
    "serviceFee": 0,
    "net": 0,
    "cardBrand": "",
    "last4": "",
    "clientName": "",
    "clientEmail": "",
    "note": "",
    "paidOn": "",
    "createdAt": "2026-01-15T09:30:00.000Z"
  }
}