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.

What is an Order?

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

Payment form creation and signature verification flow
Rendering diagram...
  1. Customer selects checkout: User clicks payment button on website
  2. Website creates HTML form: Server creates HTML form with required parameters
  3. Collect order information: Get information from database or session
  4. Prepare form data: Arrange parameters in correct format
  5. Create signature: Use HMAC-SHA256 algorithm to create signature
  6. Add signature to form: Add signature to form as hidden field
  7. Submit form: Send POST request to checkout/init endpoint
  8. Validate signature: SePay checks signature validity
  9. Redirect: If valid, redirect to payment page
  10. Payment: Customer makes payment on SePay page
  11. Callback: SePay calls back IPN URL with result

Endpoint

POST
https://pgapi-sandbox.sepay.vn/v1/checkout/init
Note

This is an endpoint for form submission, not an API endpoint.

Parameter List

merchantstringrequired
Your merchant ID (Example: MERCHANT_123)
currencystringrequired
Currency code (only VND supported)
order_amountstringrequired
Order amount (smallest unit)
operationstringrequired
Transaction type (PURCHASE or VERIFY)
order_descriptionstringrequired
Order description
order_invoice_numberstringrequired
Invoice number (required for PURCHASE, example: INV_20231201_001)
payment_methodstring
Payment method (CARD, BANK_TRANSFER, NAPAS_BANK_TRANSFER)
customer_idstring
Customer ID
success_urlstring
Redirect URL on success (Example: https://yoursite.com/success)
error_urlstring
Redirect URL on error (Example: https://yoursite.com/error)
cancel_urlstring
Redirect URL on cancel (Example: https://yoursite.com/cancel)
Note

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

Important note about input order in HTML

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.

Payment form
1
2
3
4
5
6
7
8
9
10
11
12
13
14
<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&currency=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...

Note

The payment page will display available payment methods based on your merchant configuration.

Signature Verification

Important note about fields when creating signature

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:

  1. 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
  2. Create signing string: field1=value1,field2=value2,field3=value3...
  3. Encode: base64_encode(hash_hmac('sha256', $signedString, $secretKey, true))

Signature creation example:

PHPPHP Data Signing Function
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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

Important Notes
  1. Invoice number: order_invoice_number must be unique and not duplicated. 2. Amount: Only VND supported, amount must be greater than 0 for PURCHASE transactions. 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.
Previous page
—
Next page
—