Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.paynext.com/llms.txt

Use this file to discover all available pages before exploring further.

API keys let you authenticate server-to-server requests to the PayNext API. PayNext supports scoped API keys, so each key can be limited to specific resources and access levels instead of having full access to the entire platform.

​
Overview

Scoped API keys help reduce security risk by following the least privilege principle. With scoped permissions, you can:
  • create keys for specific integrations or teams
  • allow access only to the resources an integration needs
  • separate read access from write access
  • limit the impact of a leaked or compromised key

​
Access to API Key Management

Only the following user roles can access API key settings:
RoleAPI key access
AdminFull access
DeveloperFull access
Other rolesNo access

​
Permission Model

Permissions are grouped by resource. Each resource supports one of the following access levels:
  • None – no access
  • Read – read-only access
  • Write – write access, including read access where applicable

​
Permission Groups

​
Main

ResourceAvailable access
Client SessionsNone / Write
CustomersNone / Read / Write
PlansNone / Read

​
Payments

ResourceAvailable access
PaymentsNone / Read / Write
RefundsNone / Write

​
Subscriptions

ResourceAvailable access
SubscriptionsNone / Read / Write
Subscription CancellationNone / Write

​
Endpoint-to-Permission Mapping

Each API request requires a matching permission.
MethodEndpointRequired permission
POST/client-sessionClient Sessions: Write
PATCH/client-session/{id}Client Sessions: Write
GET/customersCustomers: Read
GET/customers/{id}Customers: Read
POST/customersCustomers: Write
PATCH/customers/{id}Customers: Write
GET/paymentsPayments: Read
GET/payments/{id}Payments: Read
POST/paymentsPayments: Write
POST/payments/refund/{id}Refunds: Write
GET/plansPlans: Read
GET/plans/{id}Plans: Read
GET/subscriptions/searchSubscriptions: Read
GET/subscriptions/{id}Subscriptions: Read
POST/subscriptionsSubscriptions: Write
PATCH/subscriptionsSubscriptions: Write
POST/subscriptions/cancel/{id}Subscription Cancellation: Write
POST/subscriptions/schedule-cancel/{id}Subscription Cancellation: Write

​
Create an API Key

1

Open Developers settings

In the PayNext Dashboard, go to the Developers page and open the API Keys tab.
2

Create a new API key

Click New API key.
3

Enter basic details

Provide a name for the API key so it is easy to identify later.
4

Assign permissions

Choose the required access level for each resource using the available options:
  • None
  • Read
  • Write
5

Save the key

Click Create to generate the API key.
For security reasons, show the API key value only to the team or system that needs it. Store it in a secure secret manager and avoid sharing it in plain text.

​
Update an API Key

You can review and update permissions for an existing API key at any time. Permission changes take effect for subsequent API requests made with that key.

​
Best Practices

  • Create separate API keys per service or integration
  • Grant only the minimum required permissions
  • Avoid reusing the same key across multiple systems
  • Review old keys and remove unnecessary access
  • Rotate keys periodically
  • Restrict production and sandbox usage to different keys

​
Notes

  • Write includes Read where applicable
  • Some resources support only Write or only Read, depending on available API operations
  • API key management is available only to Admin and Developer roles