🇻🇳 Vietnam Payment Integration Guide

This guide will help you complete the basic integration of the Vietnamese Dong (VND) payment system API in 5 minutes.

📋 Prerequisites

Before you begin, make sure you have obtained the following information:

Item	Description
platform_id	Platform Merchant ID
sign_key	Platform Secret Key (for signing)
authorization	Authorization Token (required for request headers in some APIs)
API Endpoint	Sandbox/Production environment URL

🔑 Signature Mechanism

All API requests must include a sign parameter. Steps to generate the signature:

1. Sort all non-empty parameters in ASCII ascending order
2. Concatenate using key=value format, joined by &
3. Append the platform secret key at the end
4. Perform MD5 encryption, output a 32-character lowercase string

For detailed instructions, refer to: Signature Specification

📥 Deposit Flow

Create Deposit Order

curl -X POST https://api.your-domain.com/gateway/api/v1/payments \
  -H "Content-Type: application/json" \
  -d '{
    "platform_id": "your_platform_id",
    "service_id": "SVC0015",
    "payment_cl_id": "ORDER_12345",
    "amount": 5000000,
    "notify_url": "https://your-domain.com/callback",
    "request_time": 1595504136,
    "sign": "your_calculated_sign"
  }'

💡 Note: The amount unit is Vietnamese Dong (cents), please multiply by 100. For example, to collect 50,000.00 VND, pass the value 5000000

📤 Withdraw Flow

Create Withdraw Order

curl -X POST https://api.your-domain.com/gateway/api/v2/payouts \
  -H "Content-Type: application/json" \
  -d '{
    "platform_id": "your_platform_id",
    "service_id": "SVC0004",
    "payout_cl_id": "PAYOUT_12345",
    "amount": 5000000,
    "bank_name": "ACB",
    "number": "001234567890",
    "name": "NGUYEN VAN A",
    "currency": "vnd",
    "notify_url": "https://your-domain.com/callback",
    "request_time": 1595504997,
    "sign": "your_calculated_sign"
  }'

🏦 Supported Services in Vietnam

Deposit Services

Service ID	Type	Description
SVC0015	Bank Card	Bank Card Channel
SVC0016	Gateway Direct	Gateway Direct Connection
SVC0017	QR Code	QR Code Scanning
SVC0018	MOMO	MOMO PAY
SVC0019	VIETTEL	VIETTEL PAY
SVC0047	ZALO	ZALO PAY
SVC0072	MOMO Native	MOMO Native

Withdraw Services

Service ID	Type	Description
SVC0004	Bank Card	Bank Card Withdrawal
SVC0018	MOMO	MOMO Withdrawal (bank_name fill "none")
SVC0047	ZALO	ZALO Withdrawal (bank_name fill "none")