Tenant API reference

Routes under /api/tenant, for scripts that run a tenant's console. Authenticate with a developer key: Authorization: Bearer tdk_…; each route needs the capability shown. Choose test or live data with ?livemode=true|false (default false). A platform key with Act for tenants can call every route for a tenant with PayLink-Tenant: {slug}. Guide: automation API.

OpenAPI document: tenant.json. Every PayLink also serves it at /docs/api/tenant/openapi.json, with Swagger UI at /docs/api.

/overview

`GET /api/tenant/overview`

What the console's overview shows: the last 7 days, what is waiting, and how far set-up has got.

Needs a developer key with the payments.read capability.

Parameter	In	Type
`livemode`	query	boolean

/payments

`POST /api/tenant/payments`

Creates a payment (as "New payment" in the console does) and returns its checkout_url to share. Amounts in paise.

Needs a developer key with the payments.write capability.

Parameter	In	Type
`livemode`	query	boolean

Body (JSON):

Field	Type
`amount`	integer int64
`currency`	string
`reference`	string
`description`	string
`return_url`	string
`customer_name`	string
`customer_email`	string
`customer_phone`	string
`customer_id`	string
`metadata`	map of string
`expires_in_seconds`	integer int32

`GET /api/tenant/payments`

Payments, newest first, with the console's filters. Dates are UTC days (yyyy-MM-dd); amounts in paise. Answers total and total_amount for the filter.

Needs a developer key with the payments.read capability.

Parameter	In	Type
`livemode`	query	boolean
`status`	query	string
`q`	query	string
`method`	query	string
`from`	query	string
`to`	query	string
`min_amount`	query	integer int64
`max_amount`	query	integer int64
`reference`	query	string
`limit`	query	integer int32
`offset`	query	integer int32

`POST /api/tenant/payments/{id}/release`

Releases a payment a risk rule put on hold, so the payer can pay.

Needs a developer key with the payments.write capability.

Parameter	In	Type
`id`	path	string	required

Body (JSON):

Field	Type
`note`	string

`GET /api/tenant/payments/export`

The payments list as CSV (up to 50,000 rows), with the same filters as GET /payments.

Needs a developer key with the payments.read capability.

Parameter	In	Type
`livemode`	query	boolean
`status`	query	string
`q`	query	string
`method`	query	string
`from`	query	string
`to`	query	string
`min_amount`	query	integer int64
`max_amount`	query	integer int64
`reference`	query	string

`GET /api/tenant/payments/{id}/attempts/{attemptId}/proof`

The payer's UPI screenshot for an attempt. Every view is audited.

Needs a developer key with the upi.verify capability.

Parameter	In	Type
`id`	path	string	required
`attemptId`	path	string	required

`GET /api/tenant/payments/{id}`

A payment with its attempts, refunds and full journey (every event, with who did it).

Needs a developer key with the payments.read capability.

Parameter	In	Type
`id`	path	string	required

`POST /api/tenant/payments/{id}/cancel`

Cancels an open payment.

Needs a developer key with the payments.write capability.

Parameter	In	Type
`id`	path	string	required

Body (JSON):

Field	Type
`note`	string

`POST /api/tenant/payments/{id}/refunds`

A refund through the gateway, or (manual = true, reason required) a refund the merchant made outside PayLink.

Needs a developer key with the refunds capability.

Parameter	In	Type
`id`	path	string	required

Body (JSON):

Field	Type
`amount`	integer int64
`reason`	string
`manual`	boolean

/links

`GET /api/tenant/links`

Payment links, newest first; q searches title and code, state is on or off.

Needs a developer key with the links capability.

Parameter	In	Type
`livemode`	query	boolean
`q`	query	string
`state`	query	string
`limit`	query	integer int32
`offset`	query	integer int32

`POST /api/tenant/links`

Creates a payment link. Amounts in paise; leave amount out to let the payer choose.

Needs a developer key with the links capability.

Parameter	In	Type
`livemode`	query	boolean

Body (JSON):

Field	Type
`title`	string
`description`	string
`amount`	integer int64
`min_amount`	integer int64
`max_amount`	integer int64
`currency`	string
`ask_email`	boolean
`ask_phone`	boolean
`return_url`	string
`max_payments`	integer int32
`expires_at`	string
`code`	string

`GET /api/tenant/links/{id}`

One payment link.

Needs a developer key with the links capability.

Parameter	In	Type
`id`	path	string	required

`PATCH /api/tenant/links/{id}`

Turns a link on or off. A link that's off tells payers it's no longer taking payments.

Needs a developer key with the links capability.

Parameter	In	Type
`id`	path	string	required

Body (JSON):

Field	Type
`active`	boolean

`GET /api/tenant/links/{id}/qr`

The link's QR code as SVG, for printing.

Needs a developer key with the links capability.

Parameter	In	Type
`id`	path	string	required

/reports

`GET /api/tenant/reports`

The Reports page as JSON: funnel, methods, failure reasons and daily volume. A range is at most 366 days.

Needs a developer key with the reports capability.

Parameter	In	Type
`livemode`	query	boolean
`range`	query	string
`from`	query	string
`to`	query	string

/settlements

`POST /api/tenant/settlements`

Imports a gateway's settlement report (CSV, multipart field "report" or a text/csv body). Without a mapping PayLink uses the columns it recognises (the same guess the console shows); pass column numbers (0-based) to override.

Needs a developer key with the reconciliation capability.

Parameter	In	Type
`connector`	query	string
`reference`	query	integer int32
`gross`	query	integer int32
`fee`	query	integer int32
`tax`	query	integer int32
`net`	query	integer int32
`date`	query	integer int32
`settlement_ref`	query	integer int32
`paise`	query	boolean

`GET /api/tenant/settlements`

Imported reports, lines that need a look, the daily close and paid gateway payments not yet settled.

Needs a developer key with the reconciliation capability.

/disputes

`GET /api/tenant/disputes`

Disputes reported by gateways.

Needs a developer key with the disputes capability.

Parameter	In	Type
`livemode`	query	boolean

`POST /api/tenant/disputes/{id}/note`

Saves your note on a dispute (what evidence you sent).

Needs a developer key with the disputes capability.

Parameter	In	Type
`id`	path	string	required

Body (JSON):

Field	Type
`note`	string

/routing

`GET /api/tenant/routing`

The checkout order and amount ranges of the methods that are on, which are resting after errors, and failover.

Needs a developer key with the methods capability.

Parameter	In	Type
`livemode`	query	boolean

`PUT /api/tenant/routing`

Sets the checkout order and amount ranges of methods that are on, and whether failed starts move to the next gateway.

Needs a developer key with the methods capability.

Parameter	In	Type
`livemode`	query	boolean

Body (JSON):

Field	Type
`methods`	array of object
`methods[].connector`	string
`methods[].order`	integer int32
`methods[].min_amount`	integer int64
`methods[].max_amount`	integer int64
`failover`	boolean

/account-requests

`GET /api/tenant/account-requests`

Gateways the platform helps tenants get an account with, and this tenant's requests.

Needs a developer key with the methods capability.

`POST /api/tenant/account-requests`

"Get an account": records the request. For a partner-link programme the response carries the link to open.

Needs a developer key with the methods capability.

Body (JSON):

Field	Type
`connector`	string
`name`	string
`email`	string
`phone`	string
`answers`	map of string