Integration Flow

Integration Overview

This comprehensive integration guide provides step-by-step instructions for integrating with the Smilepayz payment platform. The integration process is designed to be straightforward and secure, supporting multiple regions and payment methods.

Prerequisites and Account Setup

Regional API Documentation

Select your target region to access specific API documentation:

Region	Documentation Link	Currency	Payment Methods
Brazil	Brazil API Docs	BRL	PIX, Bank Transfer
Chile	Chile API Docs	CLP	CASHIER_CL, Bank Transfer
Colombia	Colombia API Docs	COP	CASHIER_CO, Bank Transfer
India	India API Docs	INR	UPI, Bank Transfer
Indonesia	Indonesia API Docs	IDR	QRIS, Virtual Account
Mexico	Mexico API Docs	MXN	SPEI, Bank Transfer
Peru	Peru API Docs	PEN	CASHIER_PE, Bank Transfer
Philippines	Philippines API Docs	PHP	GCASH, Bank Transfer
Thailand	Thailand API Docs	THB	QRPAY, Bank Transfer

Account Acquisition

• Contact Smilepayz Staff: Please contact our business development team to obtain your integration account
• Account Verification: Complete the merchant verification process
• Documentation Access: Receive access to regional API documentation and credentials

Sandbox Environment Integration

The sandbox environment provides a safe testing environment with simulated data for development and integration testing.

Step 1: Retrieve Integration Information

Access Merchant Backend

1. Login: Access the Merchant Backend Portal
2. Environment Switch: Switch to the Sandbox tab
3. Credential Retrieval: Obtain your sandbox credentials

Sandbox Credentials

• Merchant ID: Starts with sandbox prefix in sandbox environment
• Merchant Secret: Used for signature generation (do not modify)
• Platform Public Key: For signature verification

Important Note

Sandbox credentials are for testing purposes only and cannot be used in production.

Step 2: Configure IP Whitelist and Callback URL

IP Whitelist Configuration

• Self-Configuration: Configure IP whitelist independently in sandbox
• Reference Guide: See Sandbox IP Configuration
• Development IPs: Add your development server IP addresses

Callback URL Setup

• Backend Configuration: Configure callback URL in Merchant Backend
• Request Parameter: Alternatively, include callbackUrl in API request parameters
• HTTPS Required: Ensure callback URLs use HTTPS protocol

Step 3: Generate RSA Key Pair

Key Generation Process

1. Generate Keys: Click the Generate RSA Keys button
2. Key Pair Creation: System generates RSA private key and public key
3. Public Key Save: Ensure the public key is successfully saved
4. Verification: Refresh the page to confirm public key is saved

Key Pair Validation

• Pair Matching: Verify saved public key corresponds to your private key
• Signature Errors: Mismatched key pairs will cause signature validation failures
• Key Security: Safely store your private key and never share it

Security Alert

Ensure the saved public key corresponds to the same pair as the private key used for signing. Mismatched keys will cause signature errors.

Step 4: API Integration Implementation

Base URL Configuration

• Sandbox Base URL: https://sandbox-gateway.smilepayz.com
• API Version: Use v2.0 API endpoints
• HTTPS Only: All API communications use HTTPS

SDK Integration

We provide comprehensive SDKs in multiple programming languages:

Language	Repository	Documentation
Java	Java Demo	Complete Java implementation
C#	C# Demo	.NET integration examples
PHP	PHP SDK	PHP SDK and examples
Python	Python Demo	Python integration guide
Node.js	Node.js Demo	JavaScript/Node.js examples
Golang	Golang Demo	Go language integration

Configuration Requirements

• Credential Replacement: Replace merchant ID, merchant secret, and private key with your actual credentials
• Environment Variables: Use environment variables for sensitive configuration
• Error Handling: Implement comprehensive error handling

Step 5: Order Creation and Response Handling

Success Response Processing

• Success Code: code = "00" indicates successful order creation
• Payment URL: Mock data in sandbox (not for actual payments)
• Order Number: Unique order identifier for tracking

Example Success Response

{
  "code": "00",
  "channel": {
    "paymentUrl": "https://sandbox-gateway.smilepayz.com/cashier/#/loading?tradeNo=T1112001925061115234920979"
  },
  "orderNo": "S200192eeacf6ed4f74406900c8f1039",
  "responseCode": "2009000",
  "message": "Success"
}

Sandbox Callback Testing

• Manual Callback: In sandbox, you can initiate callback requests manually
• Testing Scenarios: Test various payment scenarios and status updates
• Error Simulation: Test error handling and edge cases

Step 6: Callback Request Processing

Signature Verification

1. Public Key Retrieval: Get platform public key in sandbox
2. Signature Validation: Verify Smilepayz callback signature
3. Response Confirmation: Return SUCCESS to Smilepayz

Callback Security

• Signature Verification: Always verify callback signatures
• Request Validation: Validate all callback parameters
• Response Handling: Implement proper response handling

Production Environment Integration

The production environment handles real transactions and requires additional security measures.

Step 1: Production Credentials Setup

Environment Differences

• Separate Credentials: Production credentials are completely different from sandbox
• Access Portal: Login to Merchant Backend and switch to Production tab
• Credential Types:
  • Merchant ID: Production-specific identifier
  • Merchant Secret: Production secret for signature generation
  • Platform Public Key: Production public key for verification

Production Security

Production integration information differs completely from sandbox. Never use sandbox credentials in production.

Step 2: IP Whitelist and Callback Configuration

IP Whitelist Management

• Security Requirement: Merchants cannot set IP whitelist independently
• Support Contact: Contact customer service for IP whitelist configuration
• Security Review: All IP addresses undergo security review

Callback URL Configuration

• Backend Setup: Configure callback URL in Merchant Backend
• Request Parameter: Include callbackUrl in API request parameters
• HTTPS Mandatory: All production callback URLs must use HTTPS

Step 3: Production RSA Key Generation

Key Generation Process

1. Generate Keys: Click Generate RSA Keys button
2. Key Pair Creation: Create production RSA private and public keys
3. Public Key Save: Ensure public key is successfully saved
4. Verification: Refresh page to confirm public key is saved

Production Key Security

• Key Pair Matching: Verify saved public key matches your private key
• Secure Storage: Implement secure key storage practices
• Key Rotation: Plan for periodic key rotation

Step 4: Production API Integration

Production Base URL

• Production Base URL: https://gateway.smilepayz.com
• API Version: Use v2.0 API endpoints
• SSL Certificate: Valid SSL certificate required

SDK Implementation

Use the same SDK repositories as sandbox, but with production credentials:

Language	Repository	Production Notes
Java	Java Demo	Production-ready implementation
C#	C# Demo	.NET production examples
PHP	PHP SDK	Production PHP SDK
Python	Python Demo	Production Python guide
Node.js	Node.js Demo	Production Node.js examples
Golang	Golang Demo	Production Go integration

Step 5: Production Order Processing

Production Response Handling

• Real Transactions: Production requires actual payment or successful payout
• Success Code: code = "00" indicates successful order creation
• Payment URL: Real Smilepayz checkout URL for customer payment
• Regional Variations: Returned channel varies by region

Production Response Example

{
  "code": "00",
  "channel": {
    "paymentUrl": "https://gateway.smilepayz.com/cashier/#/loading?tradeNo=T1112001925061115234920979"
  },
  "orderNo": "200192eeacf6ed4f74406900c8f1039",
  "responseCode": "2009000",
  "message": "Success"
}

Regional Channel Information

• Channel Variations: Different payment channels by region
• Reference Documentation: See Payment Channel Model
• Regional Compliance: Ensure compliance with regional requirements

Step 6: Production Callback Processing

Callback Verification

1. Public Key Retrieval: Get production platform public key
2. Signature Validation: Verify Smilepayz callback signature
3. Response Confirmation: Return SUCCESS to Smilepayz

Production Callback Security

• Signature Verification: Mandatory signature verification for all callbacks
• Request Validation: Comprehensive parameter validation
• Error Handling: Robust error handling and logging
• Monitoring: Implement callback monitoring and alerting

Integration Best Practices

Security Guidelines

• Credential Management: Secure storage of all API credentials
• Signature Verification: Always verify request and response signatures
• HTTPS Only: Use HTTPS for all API communications
• IP Whitelisting: Restrict access to authorized IP addresses

Error Handling

• Comprehensive Logging: Log all API requests and responses
• Error Recovery: Implement retry mechanisms for transient errors
• Monitoring: Set up monitoring and alerting for integration health
• Testing: Thorough testing in sandbox before production deployment

Performance Optimization

• Connection Pooling: Implement connection pooling for API calls
• Caching: Cache static data where appropriate
• Async Processing: Use asynchronous processing for callbacks
• Load Testing: Perform load testing before production deployment

Support and Resources

Technical Support

• 24/7 Support: Round-the-clock technical support available
• Integration Assistance: Expert guidance for complex integrations
• Documentation: Comprehensive API documentation and guides
• Community: Developer community and forums

Testing Resources

• Sandbox Environment: Complete testing environment with simulated data
• Test Scenarios: Comprehensive test scenarios and edge cases
• Mock Data: Realistic mock data for testing
• Validation Tools: Tools for signature validation and testing

Compliance and Security

• Regional Compliance: Adherence to regional payment regulations
• Security Standards: Industry-standard security practices
• Audit Support: Support for security audits and compliance reviews
• Certification: Security certifications and compliance documentation