Integration Flow

Overview

This guide takes you through a full Smilepayz integration—from getting your account to going live. The flow is the same for every region; only your credentials and a few endpoints change.

Before You Start

Get Your Account

• Contact Business Development: Reach our team to obtain an integration account. Self-service registration is not available.
• Complete Verification: Finish merchant verification to receive your credentials and access to regional API documentation.

Find Your Regional API Docs

Each region has its own currency and supported payment methods. Pick yours:

Region	Documentation	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
Vietnam	Vietnam API Docs	VND	E-wallets, VietQR, Bank Transfer
Egypt	Egypt API Docs	EGP	FAWRY, Bank codes
USDT	USDT API Docs	USDT	USDT_TRC20, USDT_ERC20, USDT_BEP20

Integration Flow

Build and test against the sandbox first—it uses simulated data, so no real money moves. The same six steps apply to production; see Going Live for what changes.

Step 1: Get Your Credentials

1. Sign in to the Merchant Backend Portal.
2. Switch to the Sandbox tab.
3. Copy your credentials:
   • Merchant ID — sandbox IDs start with the sandbox prefix.
   • Merchant Secret — used to sign requests; never modify or share it.
   • Platform Public Key — used to verify Smilepayz callbacks.

Info

Sandbox credentials are for testing only and will not work in production.

Step 2: Configure IP Whitelist & Callback URL

• IP Whitelist: Set it yourself in the sandbox. Add your development server IPs—see Sandbox IP Configuration.
• Callback URL: Configure it in the Merchant Backend, or pass callbackUrl per request. It must use HTTPS.

Step 3: Generate Your RSA Key Pair

1. Click Generate RSA Keys in the backend.
2. Save the public key, then refresh the page to confirm it is stored.
3. Keep the private key secure and never share it.

Note

The saved public key must match the private key you sign with. Mismatched keys cause signature errors.

Step 4: Integrate the API

Base URL (sandbox): https://sandbox-gateway.smilepayz.com · API version: v2.0 · HTTPS only.

Start from one of our SDK demos:

Language	Repository
Java	Java Demo
C#	C# Demo
PHP	PHP SDK
Python	Python Demo
Node.js	Node.js Demo
Golang	Golang Demo

Replace the demo's merchantId, merchantSecret, and privateKey with your own. Store secrets in environment variables, not in source code.

Step 5: Create an Order

A response code of 00 means the order was created. Use the returned orderNo to track it. In the sandbox, paymentUrl is mock data and cannot take real payments.

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

To test status updates and error handling, trigger a callback manually in the sandbox.

Step 6: Handle Callbacks

1. Retrieve the platform public key.
2. Verify the callback signature—always, before acting on the data.
3. Return SUCCESS to acknowledge receipt.

Going Live (Production)

Once you have tested end to end in the sandbox, switch to production. The flow is identical—only these things change:

	Sandbox	Production
Credentials	From the Sandbox tab	A separate set from the Production tab
Base URL	https://sandbox-gateway.smilepayz.com	https://gateway.smilepayz.com
IP Whitelist	Self-service	Submitted to Customer Service
Payment URL	Mock data	Real checkout, varies by region
Funds	Simulated	Real money

To go live:

• Get production credentials from the Production tab in the Merchant Backend. They are completely separate from sandbox—never mix them.
• Submit your IP whitelist to Customer Service; you cannot set it yourself in production. Configure your production callback URL the same way as sandbox.
• Generate a production RSA key pair and refresh to confirm the public key is saved.
• Point your integration to https://gateway.smilepayz.com using your production credentials.
• Handle the response: the returned channel varies by region—see the Payment Channel Model. Get the production public key to verify live callbacks.

Note

Production handles real funds. Never use sandbox credentials in production.

Best Practices

• Protect secrets: Keep credentials out of source code; use environment variables or a secrets manager.
• Verify every callback: Always validate the signature before acting on callback data.
• Use HTTPS and IP whitelisting: Encrypt all traffic and restrict access to authorized IPs.
• Log and monitor: Record requests, responses, and callbacks for troubleshooting and audits.
• Test before launch: Run through the full flow in the sandbox before going live.

Support

• Documentation: API references and integration guides across this site.
• Technical Support: Contact our team for integration help and troubleshooting.
• Business Development: Account setup, regional onboarding, and commercial terms.