PeriPay Documentation

Introduction

Welcome to the PeriPay documentation! PeriPay is a Nepalese payment gateway aggregator that allows users to integrate various payment gateways with just a few clicks. This guide will help you get started with PeriPay and make the most of its features.

1. Get Started

1.1 Signup

To begin using PeriPay, you need to create an account.

• URL: pay.periwin.com/signup
• Required Fields:
  • Email (Username): Your email address
  • Full Name: Your complete name
  • Password: A secure password for your account

1.2 Login

After signing up, log in to your account to access the PeriPay dashboard.

• Required Fields:
  • Email (Username): Your email address
  • Password: Your account password

Upon successful login, you will be redirected to the Gateways page.

URL: /gateways

Here you will find two payment gateways (Khalti and eSewa) available with test credentials. The right card will display your API key.

2. Authorization

To authenticate your requests, you will need to obtain the authentication API. The only way to authenticate the user is through a Bearer token.

Authorization Header:

Bearer <api_key>

3. Payment Initiation

To initiate a payment, make a POST request to the following endpoint.

• Endpoint: /api/payment/process/initiate/
• Method: POST
• Authorization: Bearer token <api_key>

Request Body

{
  "return_url": "type: url",
  "amount": "positive integer (in paisa)",
  "purchase_order_id": "unique string",
  "product_name": "string",
  "customer_name": "string",
  "customer_email": "string (type: email)",
  "customer_phone": "string"
}

Example Request

{
  "return_url": "https://example.com/return",
  "amount": 12000,
  "purchase_order_id": "ORDER-123456",
  "product_name": "IPHONE 16 PRO",
  "customer_name": "John Doe",
  "customer_email": "john.doe@example.com",
  "customer_phone": "XXXXXXXXXX"
}

Response

On successful initiation, you will receive a response as follows:

{
  "payment_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "message": "Payment initiated successfully.",
  "return_url": "https://example.com/return",
  "amount": 12000,
  "purchase_order_id": "ORDER-123456",
  "product_name": "IPHONE 16 PRO",
  "payment_url": "https://pay.periwin.com/payment/process/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/",
  "expires_at": "2024-09-25T12:03:31.618825Z"
}

Redirecting the User

Redirect your users to the payment_url provided in the response, where they will be presented with various payment gateway options.

Payment Completion

Once the payment is successful, a receipt will be generated at the following endpoint:

• Receipt URL: /payment/process/<payment_id>/receipt

Users can utilize this link to view the payment status.

Returning to the Homepage

After viewing the receipt, users can click on the return home button to go back to the main URL. The redirected URL will contain the following parameters:

?amount=12000&purchase_order_id=ORDER-123456&payment_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&product_name=IPHONE+16+PRO&customer_name=John+Doe&customer_email=john.doe%40example.com&customer_phone=XXXXXXXXXX&payment_gateway=khalti&refunded=False&payment_status=initiated

Developers can extract these values to store them in their database.

Design Considerations

Color Palette

• Primary Color: #2B5B73

Typography

Use a clean and modern font similar to Google’s design guidelines. Headings should be bold and larger than body text for clarity.

Layout

Maintain ample white space for readability. Use card-based UI elements for different sections, similar to the Google Material Design principles.

Conclusion

Thank you for choosing PeriPay! We hope this documentation helps you easily integrate our payment gateway solutions. For further assistance, please contact our support team.