Channel Params Request

API Overview

The Payment Form Dynamic Fields API is used to retrieve form field rules for specified payment channels. Different payment channels may require different mandatory fields. This API helps developers dynamically generate payment forms to ensure correct parameter submission.

API Information

Request URL: /channel/formRule Request Method: POST Content-Type: application/json

Request Parameters

Parameter	Required	Type	Description
uid	Yes	string	Merchant account
currency	Yes	string	Currency
pay_code	Yes	string	Payment type code
timestamp	Yes	string	GMT timestamp
userip	Yes	string	IP address of merchant member
sign	Yes	string	32-bit uppercase MD5 signature value

Request Example

{
    "uid": "test1",
    "currency": "VND",
    "pay_code": "812",
    "timestamp": 1758210270,
    "userip": "127.0.0.1",
    "sign": "200AF28BB3E4C4F0E93EBD48DB1FF623"
}

Response Parameters

Basic Response Structure

Parameter	Field	Type	Description
Status Code	status	int	More error codes see status code table
Response Data	result	object	Returns JSON string when status code is "Success"
Message	message	string	Return message
Data Signature	sign	string	32-bit uppercase MD5 signature value

result.data Object Description

Parameter	Field	Type	Description
Payment Code	pay_code	string	Payment type code
Channel Name	name	string	Payment channel name
Channel Description	description	string	Payment channel description
Form Fields	form_fields	array	Form field rules array

form_fields Field Description

Parameter	Field	Type	Description
Field Name	name	string	Field parameter name
Field Label	label	string	Field display label
Field Type	type	string	Field type: input/select
Required	required	boolean	Whether the field is mandatory
Max Length	max_length	int	Maximum length limit for the field
Placeholder	placeholder	string	Input field placeholder text
Options List	options	array	Dropdown options list (only has value when type is select)
Validation Rules	validation_rules	array	Field validation rules array

options Option Description

Parameter	Field	Type	Description
Bank ID	bankID	int	Bank unique identifier
Bank Name	name	string	Bank display name

Response Examples

Success Response Example

{
    "status": 10000,
    "result": {
        "data": {
            "pay_code": "812",
            "name": "Bank Transfer",
            "description": "Payment through bank transfer",
            "form_fields": [
                {
                    "name": "pay_code",
                    "label": "Channel Code",
                    "type": "input",
                    "required": true,
                    "max_length": 100,
                    "placeholder": "",
                    "options": null,
                    "validation_rules": [
                        "required",
                        "string",
                        "max:100"
                    ]
                },
                {
                    "name": "bank_id",
                    "label": "Bank ID",
                    "type": "select",
                    "required": true,
                    "max_length": 100,
                    "placeholder": "Please select the corresponding Bank ID",
                    "options": [
                        {
                            "bankID": 6763,
                            "name": "AB Bank"
                        },
                        {
                            "bankID": 6764,
                            "name": "Asia Commercial Bank"
                        },
                        {
                            "bankID": 6788,
                            "name": "Vietcom Bank"
                        },
                        {
                            "bankID": 6789,
                            "name": "Vietin Bank"
                        }
                    ],
                    "validation_rules": [
                        "required",
                        "string",
                        "max:100"
                    ]
                }
            ]
        }
    },
    "message": "Successfully executed",
    "sign": "C2BBC28D47DB018175E884DAD30708D9"
}

Error Handling

When a request fails, the system will return the corresponding error status code. Common error codes include:

10000: Success
10001: Parameter Error
10002: Signature Verification Failed
10003: Payment Code Does Not Exist
10004: Currency Not Supported
10005: Merchant Account Does Not Exist

Use Cases

1. Dynamic Form Generation

// Get field rules
const formRules = await fetch('/channel/formRule', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        uid: 'test1',
        currency: 'VND',
        pay_code: '812',
        timestamp: Math.floor(Date.now() / 1000),
        userip: '127.0.0.1',
        sign: 'your_signature'
    })
});

const rules = await formRules.json();

// Dynamically generate form
rules.result.data.form_fields.forEach(field => {
    if (field.type === 'input') {
        // Generate input field
        createInputField(field);
    } else if (field.type === 'select') {
        // Generate select field
        createSelectField(field);
    }
});

2. Form Validation

// Validate form based on validation rules
function validateField(field, value) {
    const rules = field.validation_rules;
    
    if (rules.includes('required') && !value) {
        return `${field.label} is required`;
    }
    
    if (rules.includes('string') && typeof value !== 'string') {
        return `${field.label} must be a string`;
    }
    
    const maxRule = rules.find(rule => rule.startsWith('max:'));
    if (maxRule && value.length > parseInt(maxRule.split(':')[1])) {
        return `${field.label} cannot exceed ${maxRule.split(':')[1]} characters`;
    }
    
    return null; // Validation passed
}

Integration Recommendations

Caching: Recommend caching field rules to avoid frequent requests
Error Handling: Properly handle error messages returned by the API
User Experience: Provide appropriate user interface based on field types
Data Validation: Perform data validation on both client and server side
Internationalization: Display corresponding field labels based on user language

Signature Algorithm

Signature generation rules:

Sort all request parameters by parameter name ASCII code from small to large
Concatenate into string using URL key-value pair format
Add merchant secret key at the end of the string
Perform MD5 encryption on the concatenated string
Convert the encryption result to uppercase

Support

For technical support and questions, please contact our development team or refer to the complete API documentation.