VNPAY Phone POS Provider

The VNPAY Phone POS provider enables payment processing using a mobile phone as a POS terminal. The customer taps their contactless card on the merchant's phone to complete payment.

Overview

Attribute	Value
Provider Key	`VNPAY_PHONE_POS`
Payment Method	`400_CARD`
Settlement	T+1
Technology	NFC Contactless

Features

NFC card tap - Contactless payment via phone
No hardware required - Phone acts as terminal
Card network support - Visa, Mastercard, JCB, UnionPay
Real-time authorization - Instant card verification

Requirements

Merchant Phone Requirements

Requirement	Details
OS	Android 9+ or iOS 14+
NFC	Built-in NFC hardware
App	VNPAY Phone POS app installed
Connectivity	4G/WiFi

Configuration

VNPAY Phone POS is an SDK-based provider. The mobile app handles card interactions, and MQ-Pay receives IPN notifications when payments complete.

Application Configuration

typescript

import { MQPayComponent, MQPayBindingKeys, IMQPayOptions } from '@nx-3rd/mq-pay';

class MyApplication extends BaseApplication {
  preConfigure() {
    this.bind<IMQPayOptions>({ key: MQPayBindingKeys.MQ_PAY_CLIENT_OPTIONS })
      .toValue({
        vnpayPhonePos: {
          enable: true,
          isDefault: false,
          enableController: true,

          // Environment flag
          isProduction: process.env.NODE_ENV === 'production',

          // Optional: Custom notification handler
          onPaymentNotification: async (ipnData) => {
            console.log('PhonePOS payment:', ipnData);
          },
        },
      });

    this.component(MQPayComponent);
  }
}

Configuration Options

Option	Type	Required	Description
`enable`	`boolean`	Yes	Enable this provider
`isDefault`	`boolean`	Yes	Use as default provider
`enableController`	`boolean`	Yes	Auto-register IPN endpoint
`isProduction`	`boolean`	Yes	`true` for production environment
`onPaymentNotification`	`function`	No	Custom IPN handler callback

SDK-Based Provider

Phone POS is SDK-based - the VNPAY mobile app handles the NFC card interaction. MQ-Pay only receives the IPN callback after payment completion.

Payment Flow

API Usage

Create Phone POS Payment

typescript

const response = await paymentService.checkout({
  source: {
    type: 'Order',
    id: 'order-uuid-123',
  },
  payment: {
    provider: 'VNPAY_PHONE_POS',
    method: '400_CARD',
    total: 150000,
    currency: 'VND',
  },
  expiration: {
    mode: 'duration',
    milliseconds: 120000,
  },
});

Card Types Supported

Card Network	Contactless
Visa	Yes
Mastercard	Yes
JCB	Yes
UnionPay	Yes
Napas (Domestic)	Yes

Response Codes

Code	Description
`00`	Success
`05`	Do not honor
`51`	Insufficient funds
`54`	Expired card
`55`	Wrong PIN

Client Guide

Providers

Invoice Types

VNPAY Phone POS Provider ​

Overview ​

Features ​

Requirements ​

Merchant Phone Requirements ​

Configuration ​

Application Configuration ​

Configuration Options ​

Payment Flow ​

API Usage ​

Create Phone POS Payment ​

Card Types Supported ​

Response Codes ​

Related ​