Skip to content

API Integration

API Integration

To integrate with PayOnUs API, you'll need to:

  1. Sign up for an account on our Merchant Portal. Once registered, you will have access to both Sandbox and Production environments.
  2. Navigate to the Settings > API Credentials section to generate your Client ID and Client Secret.
  3. Set up your Webhook URL and retrieve your Webhook Verification Key from the portal to handle automated transaction notifications.
  4. Retrieve Your Business ID: The Business ID is required for various endpoints in both Sandbox and Production. To find it:
  5. Toggle Test Mode to OFF on the dashboard.
  6. Navigate to the Business section and copy your ID.
  7. Note: You can switch back to Test Mode after retrieving the ID.
  8. Test Your Integration: Use our sandbox environment to simulate transactions. Ensure you are using your credentials and the Business ID retrieved in the previous step to verify your integration logic.

Our API uses RESTful conventions and returns responses in JSON format. All API requests must be made over HTTPS.

Authentication

PayOnUs API uses OAuth 2.0 for authentication. You'll need to generate an access token using your API credentials before making any API calls.

Generate Access Token

  • Path: /api/v1/access-token
  • Method: POST
  • Request Body: 
    {
  "apiClientId": "your_client_id",
  "apiClientSecret": "your_client_secret"
}
  • Response Body: 
    {
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86399
}

Include the access token in the Authorization header of all API requests:

Authorization: Bearer {access_token}

Notes:

  • The same endpoint is used for both Sandbox and Production — use the appropriate base URL (https://core-sandbox.payonus.com for Sandbox, https://core.payonus.com for Production) with the corresponding environment's credentials.
  • You can only have one valid access token at a time. Generating a new access token invalides the previous one.
  • You can call the Generate Access Token endpoint for at most three (3) times in a minute. Exceeding that will return a Rate Limit Exceeded (429 Too Many Requests) response.
  • We advise you to cache your token for a bit less than expires_in value (in seconds) and setup a retry mechanism to generate and retry the request in case of Authentication Failed (401 Unauthorized) response.
  • If you are using a distributed system, you can maintain a shared cache (e.g Redis) that can be accessible by all instances of your API.

Testing

We provide a sandbox environment for testing your integration before going live. The sandbox environment mimics the behavior of the production environment but doesn't process real transactions.

Sandbox Base URL: https://core-sandbox.payonus.com Production Base URL: https://core.payonus.com

Postman Collection

Here's a collection of our endpoints that can be imported into your Postman client. - API Collection

Webhooks

Webhooks allow your application to receive real-time notifications about events that occur in your PayOnUs account. To use webhooks:

  1. Configure your webhook URL in the Merchant Dashboard
  2. Implement an endpoint on your server to receive webhook events
  3. Verify webhook signatures to ensure the events are from PayOnUs

Error Handling

PayOnUs API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

  • 2xx status codes indicate success
  • 4xx status codes indicate an error that failed given the information provided (e.g., a required parameter was omitted)
  • 5xx status codes indicate an error with PayOnUs's servers

Common Error Codes

Status Code Description
400 Bad Request - The request was unacceptable, often due to missing a required parameter
401 Unauthorized - No valid API key provided
403 Forbidden - The API key doesn't have permissions to perform the request
404 Not Found - The requested resource doesn't exist
409 Conflict - The request conflicts with another request
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Something went wrong on PayOnUs's end

Error Response Format

{
  "status": 400,
  "message": "A detailed description of the error",
  "data": {
    "statusCode": 400,
    "error": "A detailed description of the error",
    "errors": []
  }
}

Best Practices

Follow these best practices to ensure a smooth integration with PayOnUs API:

Security

  1. Never expose your API credentials in client-side code or public repositories
  2. Implement proper error handling to avoid exposing sensitive information
  3. Validate webhook signatures to ensure the events are from PayOnUs
  4. Use HTTPS for all API requests and webhook endpoints

Performance

  1. Cache access tokens until they expire to reduce authentication requests
  2. Implement retry logic with exponential backoff for failed requests
  3. Use pagination when fetching large collections of resources
  4. Minimize the number of API calls by batching operations when possible

Webhooks

  1. Respond quickly to webhook events (within 5 seconds)
  2. Implement idempotency to handle duplicate webhook events
  3. Store webhook events in your database before processing them
  4. Set up a monitoring system to track webhook delivery and processing

Testing

  1. Use the sandbox environment for all testing before going to production
  2. Test edge cases such as failed payments, refunds, and disputes
  3. Simulate webhook events to test your webhook handling logic
  4. Maintain a separate test suite for your PayOnUs integration