GIFT API

Specification Doc

Please read Onboarding first!!

Version	Date	Author	Description
1.0	10-08-2020	Phong Le	Initial draft

Flows

Voucher Flow

Methods

1. Create Gift

Allow a Merchant request to create gift with Momo

Method: POST
URL: api/gift/create

Example :

Request

{
  "requestId": "wqrwpo2343240xsad213",
  "time": 1587037711592,
  "walletId": "0902890661",
  "gifts": [
    {
      "giftId": "giftId0",
      "giftType": "1234567891",
      "amount": 40000,
      "startTime": 1587037711592,
      "endTime": 1672506000000,
      "reference": "1234567891",
      "description": "Voucher test",
      "quantity": 1
    },
    {
      "giftId": "giftId1",
      "giftType": "1234567892",
      "amount": 50000,
      "startTime": 1587037711592,
      "endTime": 1672506000000,
      "reference": "1234567892",
      "description": "Voucher test 01",
      "quantity": 2
    }
  ]
}

Response

{
  "requestId": "149290648301898",
  "referenceId ": "",
  "resultCode": 0,
  "message": "Success",
  "totalAmount": 40000,
  "gifts": [
    {
      "giftId": "giftId0",
      "status": 0,
      "statusDesc": "Success",
      "voucherId": "1234567ABCD",
      "paymentRef": "1234567",
      "quantity": 1
    },
    {
      "giftId": "giftId1",
      "status": 801,
      "statusDesc": "Invalid Gift Type",
      "voucherId": "1234567ABCDE",
      "paymentRef": "12345678",
      "quantity": 2
    }
  ]
}

Request

Method	URL
POST	api/voucher/create

Name	Type	Level	Require	Len	Description
requestId	String	L1	x	50	Unique String for each request
time	Number	L1	x		Request time with format (time zone: Asia/Ho_Chi_Minh): system miliseconds
walletId	String	L1	x	20	Momo wallet id (phone number) need to create voucher.
gifts	JsonArray	L1	x	32000	List gift, require Object[0] not null
giftId	String	L2	x	50	partner's gift_id, Unique String for each request
giftType	String	L2	x	100	MoMo will provide
amount	Number	L2	x		Amount of voucher (value [10,000 - 10,000,000])
startTime	Number	L2	x		The time can start using this voucher (time zone: Asia/Ho_Chi_Minh): system miliseconds
endTime	Number	L2	x		The time is ending for this voucher, whatever using or not (time zone: Asia/Ho_Chi_Minh): system miliseconds
reference	String	L2		50	for another purpose
description	String	L2		200	Short description of Voucher
quantity	Number	L2		2	Short description of Voucher

Response

Name	Type	Level	Require	Len	Description
requestId	String	L1	x	50	The same value with your request
resultCode	Integer	L1	x	10	Result Code of request
message	String	L1	x	300	Result message
referenceId	String	L1	x	50	Unique for each response
totalAmount	Number	L1	x		Total amount
gifts	JsonArray	L1	x	32000	List gift, result for each gift
giftId	String	L2	x	50	partner's gift_id, same with request
status	Number	L2	x		result status
statusDesc	String	L2	x	300	description for status
voucherId	String	L2		50	MoMo Voucher Id, Using for report
paymentRef	String	L2		32	Transaction Id of MoMo. Using for report
quantity	Number	L2		2	Short description of Voucher

Description

Response

resultCode: the result of each request, result of gift should check in gifts key
status: the result for each gift

2. CheckStatus

Allow partner check the result of previous transaction

Method: POST
URL: api/gift/status

Example :

Request

{
  "requestId": "wqrwpo2343240xsad213",
  "checkRequestId": "149290648301898"
}

Response

{
  "requestId": " wqrwpo2343240xsad213",
  "referenceId ": "stasdfsf",
  "resultCode": 0,
  "message": "Success",
  "data": {
    "requestId": "149290648301898",
    "referenceId ": "",
    "resultCode": 0,
    "message": "Success",
    "totalAmount": 40000,
    "gifts": [
      {
        "giftId": "giftId0",
        "status": 0,
        "statusDesc": "Success",
        "voucherId": "1234567ABCD",
        "paymentRef": "1234567",
        "quantity": 1
      },
      {
        "giftId": "giftId1",
        "status": 801,
        "statusDesc": "Invalid Gift Type",
        "voucherId": "1234567ABCDE",
        "paymentRef": "12345678",
        "quantity": 2
      }
    ]
  }
}

Request

Method	URL
POST	api/gift/status

Name	Type	Require	Len(byte)	Description
requestId	String	x	50	Unique String for each request
checkRequestId	String	x	50	Partner’s the old requestId need checking

Response

Name	Type	Level	Require	Max Len	Description
requestId	String	L1	x	50	Same with request
resultCode	Integer	L1	x		Result Code of request
referenceId	String	L1	x	50	Unique for each response
message	String	L1	x	300	Result message
data	JsonObject	L1	x	32000	Data is the same with the response data of create voucher function before
requestId	String	L2	x	50	The same value with your request
resultCode	Integer	L2	x	10	Result Code of request
message	String	L2	x	300	Result message
referenceId	String	L2	x	50	Unique for each response
totalAmount	Number	L2	x		Total amount
gifts	JsonArray	L2	x	32000	List gift, result for each gift
giftId	String	L3	x	50	partner's gift_id, same with request
status	Number	L3	x		result status
statusDesc	String	L3	x	300	description for status
voucherId	String	L3	x	50	MoMo Voucher Id, Using for report
paymentRef	String	L3		32	Transaction Id of MoMo. Using for report

3. Get Trans

Allow partner get all transaction of the day

Method: POST
URL: api/voucher/get-trans

Example :

Request

{
  "requestId": "wqrwpo2343240xsad213",
  "date": "2020-08-10",
  "offset": 1000,
  "page": 1
}

Response

{
  "requestId": " wqrwpo2343240xsad213",
  "referenceId ": "stasdfsf",
  "resultCode": 0,
  "message": "Success",
  "datas": [
    {
      "requestId": "149290648301898",
      "referenceId ": "",
      "resultCode": 0,
      "message": "Success",
      "gifts": [
        {
          "giftId": "giftId0",
          "status": 0,
          "statusDesc": "Success",
          "voucherId": "1234567ABCD",
          "paymentRef": "1234567"
        },
        {
          "giftId": "giftId1",
          "status": 801,
          "statusDesc": "Invalid Gift Type",
          "voucherId": "1234567ABCDE",
          "paymentRef": "12345678"
        }
      ]
    },
    {
      "requestId": "149290648301899",
      "referenceId ": "",
      "resultCode": 0,
      "message": "Success",
      "gifts": [
        {
          "giftId": "giftId00",
          "status": 0,
          "statusDesc": "Success",
          "voucherId": "1234567ABCD",
          "paymentRef": "1234567"
        },
        {
          "giftId": "giftId10",
          "status": 801,
          "statusDesc": "Invalid Gift Type",
          "voucherId": "1234567ABCDE",
          "paymentRef": "12345678"
        }
      ]
    }
  ]
}

Request

Method	URL
POST	api/gift/get-trans

Name	Type	Len(byte)	Require	Description
requestId	String	50	x	Unique String for each request
date	String	10	x	Date to get all trans (yyyy-MM-dd)
offset	Number	10	x	max number of row will return
page	Number	5	x	Default = 1

Response

Name	Type	Level	Len	Require	Description
requestId	String	L1	50	x	Same with request
resultCode	Integer	L1		x	Result Code of request
referenceId	String	L1	50	x	Unique for each response
message	String	L1	300	x	Result message
datas	JsonArray	L1	x		List transaction have replied for voucher function before
requestId	String	L2	x	50	The same value with your request
resultCode	Integer	L2	x	10	Result Code of request
message	String	L2	x	300	Result message
referenceId	String	L2	x	50	Unique for each response
gifts	JsonArray	L2	x	32000	List gift, result for each gift
giftId	String	L3	x	50	partner's gift_id, same with request
status	Number	L3	x		result status
statusDesc	String	L3	x	300	description for status
voucherId	String	L3	x	50	MoMo Voucher Id, Using for report
paymentRef	String	L3		32	Transaction Id of MoMo. Using for report

Glossary

Status Code

status of gift items in each request

Code	Message	Function	Status
0	Success	all	Success
801	Gift is empty	all	Fail
802	No Momo wallet matches with this phone number	all	Fail
803	Over 20 vouchers per transaction	all	Fail
804	The total amount of vouchers is more than 10.000.000 per transaction	all	Fail
805	Error when create voucher	all	Fail
806	Request Id of transaction needed to be checked is empty	all	Fail
807	No transaction found with this check request id	all	Fail
808	Invalid date format	all	Fail
809	Invalid gift type	all	Fail
810	Invalid start/ end date	all	Fail
811	There is no gift type information exists	all	Fail
812	Invalid/ Duplicate Gift Id	all	Fail
813	Invalid Gift amount	all	Fail
814	Timeout when creating gift	all	Fail

Error Code

resultCode of request

Code	Message	Function	Status
0	Success	all	Success
1	Invalid signature	all	Fail
2	Cannot decrypt message	all	Fail
3	Invalid username	all	Fail
4	Invalid wallet Id	all	Fail
5	Invalid password	all	Fail
6	Invalid Json String	all	Fail
7	Insufficient funds	all	Fail
8	Duplicate request Id	all	Fail
9	Invalid partner code	all	Fail
10	Unknown result. Please check manual to get final result	all	Fail
11	Other Error	all	Fail
13	This function is not active. please contact the administrator	all	Fail
15	Mainternance system, please try later !	all	Fail