PAY WITH WAVE REDIRECT API INTEGRATION GUIDELINE AND

API SPECIFICATION

Pay with Wave Money Technical

Integration Guideline and API Specification

1
PAY WITH WAVE REDIRECT API INTEGRATION GUIDELINE AND

API SPECIFICATION

Document Information
Version History

Versio Date Prepared Reviewed By Description

n# By
1.0 6th Nov 2018 Initial draft

2
PAY WITH WAVE REDIRECT API INTEGRATION GUIDELINE AND

API SPECIFICATION

Table of Contents
1. Introduction..................................................................................................................................4
2. Technical Integration Aspect.....................................................................................................4
2.1 How it works..............................................................................................................................4
2.2 Security......................................................................................................................................5
2.3 Environment..............................................................................................................................5
2.4 Payment Request.....................................................................................................................5
3. How to integrate..........................................................................................................................6
3.1 Prepare Pay with Wave button...............................................................................................6
Items to display on Payment Screen............................................................................................6
Generate Hash................................................................................................................................6
HTML Form......................................................................................................................................7
FAQs and Troubleshooting.............................................................................................................11

3
 PAY WITH WAVE REDIRECT API INTEGRATION GUIDELINE AND

API SPECIFICATION

Copyright
Copyright © Digital Money Myanmar Limited, 2018. All rights reserved. The information in this
document is subject to change without notice and describes only the product defined in the
introduction of this documentation. This document is intended for the use of Digital Money Myanmar
Limited partner only for the purposes of the agreement under which the document is submitted, and
no part of it may be reproduced or transmitted in any form or means without the prior written
permission of Digital Money Myanmar Limited. The document has been prepared to be used by
professional and properly trained personnel, and the partner assumes full responsibility when using it.
This document and the product it describes are considered protected by copyright according to the
applicable laws.

1. Introduction
Pay with Wave Redirect API is an online payment solution by Digital Money Myanmar Limited (Wave
Money) that allows online merchants to accept payments securely and instantly.

This document covers the essential information, processes, and other relevant aspects for merchant
technical integration with the Pay with Wave Platform. This document contains confidential
information and is not intended to be viewed by unapproved external parties. All information and
processes in the document are subject to edits and changes from Wave Money.

2. Technical Integration Aspect

2.1 How it works
WavePay Payment Gateway allows merchant to integrate to WavePay Payment Gateway with
minimum effort and enjoy the full benefits of enhanced security and full suite of payment options.
Accepting payment is easier with WavePay Payment Gateway.

4
PAY WITH WAVE REDIRECT API INTEGRATION GUIDELINE AND

API SPECIFICATION

2.2 Security
Merchants who wish to have access to the API are required to provide the client_id and client_secret,
which they Requests to access the API is only accepted on presentation of the correct credentials. All
requests from merchants systems to WavePay Payment Gateway API take place over HTTPS.
Certificate for HTTPS endpoints for callback URL need to be from recognized Certificate Authorities
(CAs), i.e., not self-signed and must implemented with standard port 443.

2.3 Environment
Merchants can use the testing environment to do their functional integrations. Once the integration
testing in test environment is finished, the switch to our production system can be made. This mean
that all endpoints for both environments and the credentials have to be obtained for both.

Environment URL
Testing https://devpayment.wavemoney.io/payment:8107
Production https://payment.wavemoney.io/payment

We will be provided the Client ID and Client Secret to access both environments.

2.4 Payment Request

The Header of Payment Request Header will have the following content.

Name Description Type Mandatory

merchant_id Merchant ID provided by Wave Money string Mandatory

order_id Order ID provided by Merchant string Mandatory

merchant_reference_id Unique ID for every transaction string Mandatory

frontend_result_url Merchant's Website URL string Mandatory

backend_result_url Merchant's Web Service callback URL string Mandatory

amount Total Amount string Mandatory

timeToLiveSeconds Time to Live for transaction ( seconds ) string Man

payment_description Payment Description to display on Payment Screen string Mandatory

merchant_name Merchant Name to display on Payment Screen string Mandatory

items Items to display on Payment Screen string Mandatory

Hash Needed for Hash Validating string Mandatory

5
PAY WITH WAVE REDIRECT API INTEGRATION GUIDELINE AND

API SPECIFICATION

3. How to integrate
WavePay Payment Gateway allows merchant to integrate to WavePay Payment Gateway with
minimum effort and enjoy the full benefits of enhanced security and full suite of payment options.
Accepting payment is easier with WavePay Payment Gateway.

3.1 Prepare Pay with Wave button

Setup Merchant Credentials

Items to display on Payment Screen

6
PAY WITH WAVE REDIRECT API INTEGRATION GUIDELINE AND

API SPECIFICATION

Generate Hash

HTML Form

Call Back
Wave System will call the “call-back URL” that will be provided in the request form.

HTTP Method - POST

Type - aplication/json
Request JSON Example

7
PAY WITH WAVE REDIRECT API INTEGRATION GUIDELINE AND

API SPECIFICATION

"status": " PAYMENT_CONFIRMED"

"merchantId": "food2u",
"orderId": "7",
"merchantReferenceId": "7",
"frontendResultUrl": "http://test-dev:8080/frontendurl",
"backendResultUrl": "http://test-dev:8080/callbackurl",
"initiatorMsisdn": "9791009080",
"amount": 1,
"timeToLiveSeconds": 300,
"paymentDescription": "shirts for Men",
"currency": "MMK",
"hashValue":
"29e9486e727ac0e4f185c3b757cf8892e59eb8d292c23f11d13926bb0bda
e798",
"additionalField1": null,
"additionalField2": null,
"additionalField3": null,
"additionalField4": null,
"additionalField5": null,
"transactionId": "360",
"paymentRequestId": "360",
"requestTime": "2019-11-06T15:38:56"

8
PAY WITH WAVE REDIRECT API INTEGRATION GUIDELINE AND

API SPECIFICATION

Property Name Type Property Description

Status mandatory Please see the status
description below
merchantId mandatory merchant_id that will
be defined and agreed
on both sides. example
- food2u, sgshop

orderId optional kinda `invoice_id` from

merchant side. there
will be only one
`order_id` for one
order whilst there can
be many
`merchantReferenceId`

merchantReferenceI mandatory, It should be a unique

d unique string every call.
frontendResultUrl mandatory redirect url reponse to
web

backendResultUrl mandatory call back url to

merchant server

initiatorMsisdn mandatory purchaser msisdn

amount mandatory total amount

timeToLiveSeconds mandatory time out amount. Limit
10 minutes
paymentDescription optional a brief title or
description of the
buying item. example -
3 Tuna Sandwiches

currency optional

transactionId MFS billcollect

transactionId

paymentRequestId payment_request primary

key

requestTime now() -- serverTime

hashValue hash_hmac(merchantId+or
derId+amount+backendRes

9
PAY WITH WAVE REDIRECT API INTEGRATION GUIDELINE AND

API SPECIFICATION

ultUrl+merchantReferenc
eId+initiatorMsisdn+tra
nsactionId+paymentReque
stId+requestTime) --
with hash secret key

10
PAY WITH WAVE REDIRECT API INTEGRATION GUIDELINE AND

API SPECIFICATION

status
{
OTP_REQUESTED
OTP_CONFIRMED
PAYMENT_INITIATED
PAYMENT_CONFIRMED
PAYMENT_REQUEST_CANCELLED
INVALID_HASH
OTP_GENERATION_FAILED
OTP_CONFIRMATION_FAILED
INSUFFICIENT_BALANCE
INVALID_PIN
ACCOUNT_LOCKED
BILL_COLLECTION_FAILED -- errors apart from
INSUFFICIENT_BALANCE,INVALID_PIN,ACCOUNT_LOCKED
PAYMENT_CALLBACK_FAILED
PAYMENT_CALLBACK_SUCCESS
PAYMENT_CONFIRMED
TRANSACTION_TIMED_OUT -- transaction has timed out when committing the payment
PAYMENT_RETRIEVAL_FAILED -- issue in retrieving payment details
MERCHANT_RETRIEVAL_FAILED -- issue in retrieving merchant details
}

FAQs and Troubleshooting

As a Customer

1. When I am at checkout/confirmation page and select “Pay with Wave Money”, do I

need to enter full Wave Money Account Mobile Number?

No, customer only required to enter Mobile Number prefix with ‘9’, mobile number
prefix ‘0’ and country code ‘(+95)’ are not required.

For e.g. 979100999,978560801

As a Developer

1. Does Wave Money take responsibility for the communication between client &
server?

11
PAY WITH WAVE REDIRECT API INTEGRATION GUIDELINE AND

API SPECIFICATION

No, communication between the client (web/app) and the server (merchant server) is
the developer responsibility.

3. Can I share Client_ID and Client_secret to publicly?

No, you should not your Client_ID and Client_Secret to publicly, you must be kept
secret and never appear anywhere publicly, otherwise anyone could make
transactions on your behalf.

12