Quick Start

Main Features

• Payment processing: Receive payment information from customers
• Transaction security: Encrypt and protect payment data
• Bank connection: Communicate with banks and card organizations
• Result notification: Send transaction information to your system

General Operation Flow

Getting Started with Bank Transfer QR Code Scanning

Step 1: Register an account

Visit https://my.sepay.vn/register and register a SePay account. Choose a suitable service package after registration.

If you already have an account, visit https://my.sepay.vn/pg/payment-methods to activate the Payment Gateway.

Activate Payment Gateway:

In the "PAYMENT GATEWAY" section, go to "Register". On the "Payment Methods" screen, select "Start now":

Click to expand

You can choose to start with Sandbox and click "Start integration guide":

Click to expand

SePay supports integration via API with PHP SDK and NodeJS SDK. Click continue:

Click to expand

You will receive integration information (copy MERCHANT ID and SECRET KEY for later use), keep this screen and proceed with the following steps:

Click to expand

Step 2: Create payment form on your system

Install SDK (choose PHP or NodeJS)

composer require sepay/sepay-pg

Initialize payment form with order information and security signature:

• YOUR_MERCHANT_ID: MERCHANT ID you copied from integration information in step 1
• YOUR_MERCHANT_SECRET_KEY: SECRET KEY you copied from integration information in step 1

<?php
 
require_once 'vendor/autoload.php';
 
use SePay\SePayClient;
use SePay\Builders\CheckoutBuilder;
 
// Initialize client
$sepay = new SePayClient('YOUR_MERCHANT_ID', 'YOUR_MERCHANT_SECRET_KEY', 'sandbox');
 
// Create checkout data
$checkoutData = CheckoutBuilder::make()
    ->currency('VND')
    ->orderInvoiceNumber('INV-' . time())
    ->orderAmount(100000)
    ->operation('PURCHASE')
    ->orderDescription('Test payment')
    ->successUrl('https://example.com/order/DH123?payment=success')
    ->errorUrl('https://example.com/order/DH123?payment=error')
    ->cancelUrl('https://example.com/order/DH123?payment=cancel')
    ->build();
 
// Render checkout form to UI
echo $sepay->checkout()->generateFormHtml($checkoutData);
 

Result: payment form received (Customize the interface to match your system):

Click to expand

When submitting the payment form, it will redirect to SePay's payment gateway:

Click to expand

Create endpoints to receive callbacks from SePay:

// success_url - Handle successful payment
Route::get('/payment/success', function() {
  // Show success page to customer
  return view('payment.success');
});
 
// error_url - Handle failed payment
Route::get('/payment/error', function() {
  // Show error page to customer
  return view('payment.error');
});
 
// cancel_url - Handle canceled payment
Route::get('/payment/cancel', function() {
  // Show cancel page to customer
  return view('payment.cancel');
});

Add the endpoints you created to success_url, error_url, cancel_url when creating the payment form.

Step 3: Configure IPN

On the integration information screen from step 1, enter your IPN endpoint:

Click to expand

Save the IPN configuration.

{
  "timestamp": 1759134682,
  "notification_type": "ORDER_PAID",
  "order": {
      "id": "e2c195be-c721-47eb-b323-99ab24e52d85",
      "order_id": "NQD-68DA43D73C1A5",
      "order_status": "CAPTURED",
      "order_currency": "VND",
      "order_amount": "100000.00",
      "order_invoice_number": "INV-1759134677",
      "custom_data": [],
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36",
      "ip_address": "14.186.39.212",
      "order_description": "Test payment"
  },
  "transaction": {
      "id": "384c66dd-41e6-4316-a544-b4141682595c",
      "payment_method": "BANK_TRANSFER",
      "transaction_id": "68da43da2d9de",
      "transaction_type": "PAYMENT",
      "transaction_date": "2025-09-29 15:31:22",
      "transaction_status": "APPROVED",
      "transaction_amount": "100000",
      "transaction_currency": "VND",
      "authentication_status": "AUTHENTICATION_SUCCESSFUL",
      "card_number": null,
      "card_holder_name": null,
      "card_expiry": null,
      "card_funding_method": null,
      "card_brand": null
  },
  "customer": null,
  "agreement": null
}

Create IPN endpoint to receive JSON data from SePay

The endpoint is the one you configured in IPN:

Route::post('/payment/ipn', function(Request $request) {
  $data = $request->json()->all();
 
  if ($data['notification_type'] === 'ORDER_PAID') {
      $order = Order::where('invoice_number', $data['order']['order_invoice_number'])->first();
      $order->status = 'paid';
      $order->save();
  }
 
  // Return 200 to acknowledge receipt
  return response()->json(['success' => true], 200);
});

Step 4: Testing

Now you can test by creating an order on the form integrated in step 2.

Then return to the integration information screen and click continue to check the results:

Click to expand

Scenario:

• When the user submits the payment form on your website, the system will redirect to SePay's payment page.
• On successful payment: SePay redirects to your /payment/success endpoint and sends data to the IPN endpoint you configured
• On failed payment: SePay redirects to your /payment/error endpoint
• On cancelled payment: SePay redirects to your /payment/cancel endpoint

Step 5: Go live

Steps to perform:

1. Link a real bank account
2. From https://my.sepay.vn/ go to Payment Gateway and select Register → In "Bank transfer QR code scanning" select "Start now" and continue until the screen shown below and select "Switch to Production"

Click to expand

3. After Switching to Production, you will receive the official "MERCHANT ID" and "SECRET KEY"

Click to expand

4. Update endpoint to Production: https://pay.sepay.vn/v1/checkout/init
5. For SDK users: update environment variables from Sandbox to Production (when initializing client)
6. Update Sandbox "MERCHANT ID" and "SECRET KEY" to official "MERCHANT ID" and "SECRET KEY"
7. Update IPN URL to Production
8. Update Callback URLs to Production