Referral Integration Document

1. Auth get access token

POST {{base_url}}/mgm/auth

Req Header

Content-Type    : application/json

Req Body

{
    "username": "yourcompany",
    "password": "@@@123478##"
}

Response

{
  "status": "success",
  "code": "0",
  "message": "successful",
  "data": {
    "access_token": "fd8726cb-aade-4d9d-9123-dd087007e0e2",
    "token_type": "bearer",
    "expires_in": 35999,
    "expires_at": "2023-09-12T21:21:51+0700"
  }
}

CURL

curl --location -g '{{base_url}}/mgm/auth' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "yourcompany",
    "password": "@@@123478##"
}'

1. Store profile

POST {{base_url}}/mgm/v1/profile

Req Header

Content-Type    : application/json
Authorization   : Bearer {{access_token}}

Req Body

{
    "user_id" : "acc001",
    "full_name": "Nguyễn Văn A",
    "id_number": "033085000123",
    "tax_code": "0904569900",
    "req_time": "2023-01-01T14:00:05+0700",
    "payment_info": {
        "account_number": "0000111122223333A",
        "account_name": "NGUYEN VAN A",
        "bank_name": "Techcombank",
        "bank_branch_name": "Hoan Kiem",
        "bank_address": "44 Trang Tien, Hoan Kiem, Ha Noi",
        "swift_code": "VTCBVNVX",
        "expire_date": "2028-06-01"
    }
}

Param	Required?	Type	Description, example
user_id	R	string	Mã tài khoản
full_name	R	string	Họ và tên
id_number	R	string	Số CMND hoặc CCCD
tax_code	O	string	Mã số thuế cá nhân
req_time	R	date_time	Thời gian gọi API, ISO-8601
payment_info.account_number	R	string	Số tài khoản ngân hàng
payment_info.account_name	R	string	Tên tài khoản ngân hàng
payment_info.bank_name	R	string	Tên ngân hàng
payment_info.bank_branch_name	O	string	Tên chi nhánh ngân hàng
payment_info.bank_address	O	string	Địa chỉ ngân hàng
payment_info.swift_code	R	string	Mã quốc tế bank, của MB: MSCBVNVX
payment_info.expire_date	O	date	Ngày hết hạn của tài khoản / thẻ

Response

{
  "status": "success",
  "code": "0",
  "message": "successful",
  "data": {
    "user_id": "acc001",
    "resp_time": "2023-01-01T14:00:05+0700"
  }
}

CURL

curl --location -g '{{base_url}}/mgm/v1/profile' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
    "user_id" : "acc001",
    "full_name": "Nguyễn Văn A",
    "id_number": "033085000123",
    "tax_code": "0904569900",
    "payment_info": {
        "account_number": "0000111122223333A",
        "account_name": "NGUYEN VAN A",
        "bank_name": "Techcombank",
        "bank_branch_name": "Hoan Kiem",
        "bank_address": "44 Trang Tien, Hoan Kiem, Ha Noi",
        "swift_code": "VTCBVNVX",
        "expire_date": "2028-06-01"
    }
}'

1. Store transaction

POST {{base_url}}/mgm/v1/txn

Req Header

Content-Type    : application/json
Authorization   : Bearer {{access_token}}

Req Body

{
    "txn_id": "txn001",
    "to_user_id": "acc001",
    "ref_id": "ref000000001",
    "amount": 10000.0,
    "pit": 1000.0,
    "net_amount": 9000.0,
    "txn_time": "2023-01-01T14:00:03+0700",
    "balance_before": 100000.0,
    "balance_after": 90000.0,
    "req_time": "2023-01-01T14:00:03+0700"
}

Param	Required?	Type	Description, example
txn_id	R	string	Mã giao dịch
txn_time	R	date_time	Thời gian giao dịch, ISO-8601
req_time	R	date_time	Thời gian gọi API, ISO-8601
to_user_id	R	string	ID tài khoản nhận
ref_id	R	string	Mã REF giới thiệu
amount	R	number	Số tiền thưởng
pit	R	number	Thuế tạm tính
net_amount	R	number	Số tiền thưởng sau thuế
balance_before	R	number	Số dư trước TK chi
balance_after	R	number	Số dư sau TK chi

Response

{
  "status": "success",
  "code": "0",
  "message": "successful",
  "data": {
    "txn_id": "txn001",
    "resp_time": "2023-01-01T14:00:05+0700"
  }
}

CURL

curl --location -g '{{base_url}}/mgm/v1/txn' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
    "user_id" : "acc001",
    "full_name": "Nguyễn Văn A",
    "id_number": "033085000123",
    "tax_code": "0904569900",
    "payment_info": {
        "account_number": "0000111122223333A",
        "account_name": "NGUYEN VAN A",
        "bank_name": "Techcombank",
        "bank_branch_name": "Hoan Kiem",
        "bank_address": "44 Trang Tien, Hoan Kiem, Ha Noi",
        "swift_code": "VTCBVNVX",
        "expire_date": "2028-06-01"
    }
}

1. Error codes

Error Code	Error Message	Status
0	Successful (thành công)	success
1	Authorization failed, access token is invalid	error
2	Bad request	error
3	Password is not correct	error
11	Field must required: {field_name}	error
12	Field is invalid: {field_name}: {field_value}	error
13	Field is not existed: {field_name}	error
14	Field already existed: {field_name}	error
41	{item} is not existed. Ex: acc01 is not existed	error
44	{item} is inactive	error
99	Unknown error	error
500	Internal error: {more_info}	error

5. Environments

	DEV	PROD
{{base_url}}	https://mgm-dev.yourcompany.superapps.vn	Chờ cấp phát
username	yourcompany	Chờ cấp phát
password	@@@123478##	Chờ cấp phát