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 results back to your system

Overall Workflow

Get Started with Bank Transfer QR Code

• 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, go to https://my.sepay.vn/pg/payment-methods to activate the Payment Gateway

  • Activate the Payment Gateway:

    • In the "PAYMENT GATEWAY" section, click "Register"

    • On the "Payment Methods" screen, select "Get Started" (see image below)

      

    • You can choose to start with the Sandbox environment and click “Start Integration Guide”

      

    • SePay supports API integration using both PHP SDK and NodeJS SDK

      • Click Continue

        

    • You will receive integration information (copy your MERCHANT ID and SECRET KEY to use in later steps). Keep this screen open and proceed to the next step.

      

• Step 2: Create a Payment Form in Your System

  • Install the SDK (choose PHP or NodeJS)

    PHPNodeJS

    Copy

    php

    Note

    • Learn more about PHP SDK integration Here

    • Learn more about NodeJS SDK integration Here

  • Initialize the payment form with your order details and a security signature:

    • YOUR_MERCHANT_ID: The MERCHANT ID copied in Step 1
    • YOUR_MERCHANT_SECRET_KEY: The SECRET KEY copied in Step 1
    SDK PHPSDK NodeJSPHP

    Copy

    php

  • The result is a payment form (customize its UI according to your system)

    

  • When submitting the payment form, users will be redirected to SePay’s payment gateway.

    

    Note

    • After payment completion, SePay will return results via: Success (success_url), Failed (error_url), or Cancelled (cancel_url). You need to create endpoints to handle SePay’s callback.

  • Create endpoints to receive callbacks from SePay:

    PHPCopy

    // 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 these endpoints (success_url, error_url, cancel_url) when generating the payment form.

• Step 3: Configure IPN

  What is IPN (Instant Payment Notification)?

  • IPN is an endpoint on your server that receives real-time transaction notifications from SePay.
  • Learn more about IPN
  • On the integration info screen from Step 1, enter your IPN endpoint.

    

  • Save your IPN configuration.
  Note

  • When a transaction is successful, SePay will send a JSON payload to your IPN endpoint:
  IPN JSONCopy

  {
    "timestamp": 1759134682,
    "notification_type": "ORDER_PAID",
    "order": {
      "id": "20",
      "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": "11",
      "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 an IPN endpoint to receive JSON data from SePay:

    • The endpoint must match the one you configured in the IPN settings
      PHPCopy

      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: Test Integration

  • You can now test by creating an order using the form you integrated in Step 2.

  • Then return to the integration info screen and click Continue to verify the result.

    

  • Test scenario:

    • When the user submits the payment form on your website, the system redirects to SePay’s payment page.
    • If the payment succeeds: SePay redirects to your /payment/success endpoint and sends transaction data to your configured IPN endpoint.
    • If the payment fails: SePay redirects to your /payment/error endpoint.
    • If the payment is canceled: SePay redirects to your /payment/cancel endpoint.

• Step 5: Go Live

  Requirements

  • You must have a personal or business bank account.

  • Integration and testing must be completed in the Sandbox environment.

  • Steps to go live:

    • Link your real bank account.
    • From https://my.sepay.vn/, go to Payment Gateway → Register, select Bank Transfer via QR Code → Get Started, continue until you reach the screen shown below, then click Switch to Production.

      

    • After switching to Production, you will receive your official "MERCHANT ID" and "SECRET KEY".

      

    • Update your endpoint to Production: https://pay.sepay.vn/v1/checkout/init
    • If using SDK, update environment variables from Sandbox to Production (when initializing the client).
    • Replace Sandbox "MERCHANT ID" and "SECRET KEY" with the official ones.
    • Update your IPN URL to Production.
    • Update all Callback URLs to Production.
    For NAPAS QR Bank Transfers

    • Document submission required — See details here
    For Card Payments

    • Document submission required — See details here