Create Payment Form
The create order API allows you to create one-time or recurring payment transactions through SePay. You need to submit an HTML form with parameters and signature to the checkout/init endpoint to redirect customers to the payment page.
In SePay payment gateway, an order is an information package describing a payment request with main attributes such as amount, transaction description, invoice number, customer, and callback URLs for system processing. The payment form initialization API uses this information package to create one-time transactions; you just need to create a valid HTML form and submit to the checkout/init endpoint to redirect customers to the payment page.
Order Creation Flow
- Customer selects checkout: User clicks payment button on website
- Website creates HTML form: Server creates HTML form with required parameters
- Collect order information: Get information from database or session
- Prepare form data: Arrange parameters in correct format
- Create signature: Use HMAC-SHA256 algorithm to create signature
- Add signature to form: Add signature to form as hidden field
- Submit form: Send POST request to
checkout/initendpoint - Validate signature: SePay checks signature validity
- Redirect: If valid, redirect to payment page
- Payment: Customer makes payment on SePay page
- Callback: SePay calls back IPN URL with result
Endpoint
https://pgapi-sandbox.sepay.vn/v1/checkout/initThis is an endpoint for form submission, not an API endpoint.
Parameter List
The success_url, error_url, and cancel_url parameters only work when your application is running on a publicly accessible domain or IP. If you are developing on localhost, use tools to expose your local environment such as ngrok, localtunnel, or similar.
Basic Order Creation Example
Create HTML form
When building your own HTML form, keep the exact order of inputs as in the sample form below so the signing and processing on SePay side matches exactly; changing field positions may cause invalid signature.
<form action="https://pay-sandbox.sepay.vn/v1/checkout/init" method="POST"><input type="hidden" name="merchant" value="MERCHANT_123" /><input type="hidden" name="currency" value="VND" /><input type="hidden" name="order_amount" value="100000" /><input type="hidden" name="operation" value="PURCHASE" /><input type="hidden" name="order_description" value="Payment for order #12345" /><input type="hidden" name="order_invoice_number" value="INV_20231201_001" /><input type="hidden" name="customer_id" value="CUST_001" /><input type="hidden" name="success_url" value="https://yoursite.com/payment/success" /><input type="hidden" name="error_url" value="https://yoursite.com/payment/error" /><input type="hidden" name="cancel_url" value="https://yoursite.com/payment/cancel" /><input type="hidden" name="signature" value="a1b2c3d4e5f6..." /><button type="submit">Pay now</button></form>
Response:
After submitting the form, the system will redirect the user to SePay's payment page:
https://pgapi-sandbox.sepay.vn?merchant=MERCHANT_123¤cy=VND&order_amount=100000&operation=PURCHASE&order_description=Payment%20for%20order%20%2312345&order_invoice_number=INV_20231201_001&customer_id=CUST_001&success_url=https%3A%2F%2Fyoursite.com%2Fpayment%2Fsuccess&error_url=https%3A%2F%2Fyoursite.com%2Fpayment%2Ferror&cancel_url=https%3A%2F%2Fyoursite.com%2Fpayment%2Fcancel&signature=a1b2c3d4e5f6...
The payment page will display available payment methods based on your merchant configuration.
Signature Verification
When creating signature, keep the exact order of fields in signedFields as in the sample code (do not reorder) so the signature string matches SePay's side.
Signature is created from form parameters according to these rules:
- Filter signing fields: Only sign fields in the allowed list:
merchant, operation, payment_method, order_amount, currency, order_invoice_number, order_description, customer_id, success_url, error_url, cancel_url - Create signing string:
field1=value1,field2=value2,field3=value3... - Encode:
base64_encode(hash_hmac('sha256', $signedString, $secretKey, true))
Signature creation example:
function signFields(array $fields, string $secretKey): string {$signed = [];$signedFields = array_values(array_filter(array_keys($fields), fn ($field) => in_array($field, ['merchant','operation','payment_method','order_amount','currency','order_invoice_number','order_description','customer_id','success_url','error_url','cancel_url'])));foreach ($signedFields as $field) {if (! isset($fields[$field])) continue;$signed[] = $field . '=' . ($fields[$field] ?? '');}return base64_encode(hash_hmac('sha256', implode(',', $signed), $secretKey, true));}
Example signature string:
merchant=MERCHANT_123,operation=PURCHASE,order_amount=100000,currency=VND,order_invoice_number=INV_20231201_001,order_description=Payment for order #12345,customer_id=CUST_001,success_url=https://yoursite.com/success,error_url=https://yoursite.com/error,cancel_url=https://yoursite.com/cancel
- Invoice number:
order_invoice_numbermust be unique and not duplicated. 2. Amount: Only VND supported, amount must be greater than 0 forPURCHASEtransactions. 3. Callback URLs: Must be publicly accessible URLs from the internet. 4. Signature: Always verify signature to ensure data integrity. 5. Environment: Use sandbox for testing, production for real transactions.