ShopeePay Payment API V1.54

Payment API Document

Version 1.54 - 12 Oct 2020

Table of Contents
1. Introduction 3
1.1 About this Document 3
1.2 Intended Audience 3
1.3 Version Control 3
2. Definitions 4
2.1 Payment Methods 4
2.2 Term Definitions 5
3. System Requirements 6
3.1 Prerequisite 6
3.2 API Rules 7
3.2.1 Protocol Rules 7
3.2.2 Parameter Specifications 8
3.2.2.1 Request Header 8
3.2.2.2 Payment Amount 8
3.2.3 Security Specification 9
3.2.3.1 Signature 9
3.2.4 Access Nodes 11
4. Payment Method API 12

4.1 Merchant Presented Mode (MPM) 12
4.1.1 User Payment Flow 12
4.1.2 Merchant Process 14
4.1.3 APIs 16
4.1.3.1 Create Dynamic QR API 16
4.1.3.2 Notify Transaction Status 19
4.1.3.3 QR Invalidate API 20
4.1.3.4 Check Payment Status API 21
4.1.3.5 Create Refund API 21
4.2 Customer Presented Mode (CPM) 22
4.2.3 APIs 27
4.2.3.1 Create CPM Payment 27
4.2.3.3 Create Void API 29
ShopeePay Payment APIs V1.54

1


4.3 App-to-app Redirection (Jump App) 30
4.3.3 APIs 34
4.3.3.1 Create Order 34
4.3.3.2 Notify Transaction Status 35
4.3.3.4 Create Void API 36
5. Common APIs 37

5.1 Notify Transaction Status 37
5.2 Check Payment Status API 39
5.3 Create Refund API 42
5.4 Create Void API 44
5.5 Set Merchant API 46
5.6 Set store API 50
5.7 Get Transactions API 54
Appendix 56
Appendix 1A - Transaction Types 56
Appendix 1B - Payment Status 56
Appendix 1C - Transaction Status 56
Appendix 2 - Point of Initiation 57
Appendix 3 - Merchant Category Codes (MCC) 58
Appendix 4 - National Identity Types 59
Appendix 5 - Error Codes 60
Version control 61


2

1. Introduction
1.1 About this Document
This document is the official manual for integration with ShopeePay Payment Application
Programming Interfaces (APIs).
It describes the APIs between ShopeePay and any client system which intends to offer
ShopeePay as a payment option in their system, such as merchant aggregator systems,
point-of-sale (POS) systems, Independent Software Vendor (ISV) system and online commerce
platforms.
This document is designed to be read in order.
1.2 Intended Audience

The intended audience for this document are technical personnels and programmers with
experience in payment integrations.
1.3 Version Control

Please refer to the end of this document for detailed changes between versions.


3

2. Definitions
2.1 Payment Methods

1) Merchant Presented Mode (MPM)
The client generates transaction QR according to ShopeePay payment protocol, containing
transaction amount. User will scan the QR code to make payment. Clients will be notified via
callback about the payment status of the transaction.

2) Customer Presented Mode (CPM)
The user will show his user QR code to the cashier at the merchant store. Cashier will enter the
payment amount and scan the user’s QR code in order to make payment directly.

3) App-to-app Redirect (Jump App)

The user will select ShopeePay as a payment method from an external app. External app will
redirect the user to the ShopeePay/Shopee app to complete payment. Upon payment success,
user can jump back to the external app to view their order status.


4

2.2 Term Definitions
Term Definition
Client Refers to the party making API calls
Merchant A business entity that can have one or more stores operating under it
Store A shop at a physical location offering ShopeePay as a payment method
Terminal ID If terminal ID information is contained in QR code scanned by the user, the
payment transaction will contain this identifier of the merchant’s terminal that
the payment was made at.
User ID For on-us payments, the user_id_hash is an alphanumeric string of the hashed
Hash ShopeePay userid making payment.

For off-us payments (ID only), the user_id_hash is a numeric string of the
primary account number of the user making payment.
Signature Signature is created based on shared secret key and algorithm, used by
ShopeePay and client to verify each other’s identity in every API request. The
signature algorithm is created and provided by ShopeePay. The common
signature modes used are HMAC, SHA-256, Base64
Secret Key A secret key that is shared between ShopeePay Server and the Client. This key
is used to generate the Signature to authenticate the client.

[ Note ] Never hard code the secret key in a frontend application. All API calls
should only be made from the Client’s servers.


5

3. System Requirements
3.1 Prerequisite
Once commercial agreement between ShopeePay and client is finalised, each merchant will be
assigned the following for integration testing purposes
Name Description
Client ID Unique identifier to identify the caller of each request, to be added to
the request header of each API call.
Secret Key Only ShopeePay and the Client should know the shared secret. Secret
Key will be shared offline.


6

3.2 API Rules
3.2.1 Protocol Rules

This specifies the rules for calling APIs in this document.

Table 1: API formats and protocol rules
Component Format/Method
Transfer Mode HTTPS
Submit Mode POST Method
Date Format UNIX
Char Encoding UTF-8
Signature HMAC, SHA-256, Base64


7

3.2.2 Parameter Specifications
3.2.2.1 Request Header
All requests will require this 2 parameters in the header
Name Description
Client ID Unique identifier for caller, issued by ShopeePay
Signature Generated using the shared secret that is given by Shopee to
authenticate the API caller.

3.2.2.2 Payment Amount
Payment amount will be:
● Integer format
● Inflated by a factor of 100
Example:
● Smallest amount will be 001, which represents 0.01
● For currencies like IDR, that do not have denomination in cents, the smallest amount will

be 100, which represents 1.00 IDR (1 Rupiah)
There will not be a default currency. The current supported currency will be:
● IDR: Indonesia Rupiah
● MYR: Malaysia Ringgit
● PHP: Philippines Peso
● SGD: Singapore Dollar


8

3.2.3 Security Specification
3.2.3.1 Signature
A signature should be generated from the request body to authenticate the request. A secret key
is needed to sign the request body. Please request from our technical team if you do not have
one.
The signature is a hash-based message authentication code (HMAC) using the SHA256
cryptographic function and the aforementioned secret key, operated on the request JSON.
Python import hmac

import hashlib
def generate_signature(request_json):
return hmac.new(<secret_key>, request_json, hashlib.sha256)
.digest()
.encode('base64')
.rstrip("\n")
Golang import (
"crypto/hmac"
"crypto/sha256"
"encoding/base64"
)

// Sign - sign the `payload` with `key`
func Sign(payload, key []byte) string {
mac := hmac.New(sha256.New, key)
// Cannot return error
if _, err := mac.Write(payload); err != nil {
return ""
}
return base64.StdEncoding.EncodeToString(mac.Sum(nil))
}
Javascript let hash = CryptoJS.HmacSHA256(body, secret)

let sig = CryptoJS.enc.Base64.stringify(hash).replace(/\n+$/, '')

9

Include the signature in the request
The signature should be added in the HTTP header in the following format:
X-Airpay-ClientId: <clientid>
X-Airpay-Req-H: <request_signature>
Signature Example
Perform the following steps to sign the message.
Secret: p
z148x0gXyPCLHxnlhEydNLg55jni91i
1. Extract the request body to be signed. For example:
{"request_id": "","store_ext_id": "externalstore","merchant_ext_id":

"externalmerchant","amount": 1000,"terminal_id":
"terminal","convenience_fee_percentage": 0,"convenience_fee_fixed":
0,"convenience_fee_indicator": "","additional_info": "","currency":
"IDR","qr_validity_period": 1000,"payment_reference_id": "testreference"}
2. Hash the JSON content by using the SHA256 algorithm.
5f5532bf23018674788770f43743522dff1af5782243fab06b1e8677a7391d4c
3. Encode to Base64
X1UyvyMBhnR4h3D0N0NSLf8a9XgiQ/qwax6Gd6c5HUw=
3.2.3.2 Signature Verification
Upon receiving the API response, the Client should verify the signature of the response in the
following way:
1. Use the shared secret to sign the response body to obtain the response signature.
2. Compare the generated signature to the signature in the header of the API response.
3. Signatures from steps #1 and #2 must be identical. If they are different, the response
should not be trusted.

10

3.2.4 Access Nodes

ShopeePay access nodes are country specific, each country will have their own API domains to
be called.
Region Domain Suffix
Region Abbreviation Code
Indonesia ID co.id
Malaysia MY com.my
Philippines PH com.ph
Singapore SG sg
Append the region code to the end of the domain.

Environment Domain
sandbox api.uat.wallet.airpay.<region>
live api.wallet.airpay.<region>


11

4. Payment Method API

Payment Method APIs refers to APIs that are used specifically for certain payment methods.
Currently there are two payment methods: Merchant Presented Mode (MPM) and Customer
Presented Mode (CPM).
4.1 Merchant Presented Mode (MPM)
4.1.1 User Payment Flow

1) The cashier generates dynamic QR code containing payment amount correspondingly,
as shown in figure 4.1.1
2) User clicks on “Scan” icon on ShopeePay homepage and scan the QR code, as shown in
figure 4.1.2
3) User confirms the payment amounts and apply any merchant voucher if applicable, as
shown in figure 4.1.3
4) The user enter PIN to proceed with the payment, as shown in figure 4.1.4
5) User is prompted of successful payment after completing the payment, as shown in
figure 4.1.5. Merchant delivers the products to user after receiving notification of
successful payment from ShopeePay system.
See screenshots on the following page for the front-end user flow on ShopeePay.

12

Figure 4.1.1 Dynamic QR Figure 4.1.2 U

ser scan QR Figure 4.1.3 C
heck payment
generated by cashier code on ShopeePay amount

Figure 4.1.4 Enter PIN Figure 4.1.5 User redirected

to payment success page


13

4.1.2 Merchant Process
1) The client backend generates a QR code by calling ShopeePay system (Create

merchant-presented dynamic QR API) and displays it to the user to be scanned
2) The user scan the QR code, checks payment amount and input PIN to proceed with the
payment
3) ShopeePay system returns the transaction result to user and the user is redirected to
payment successful page.
4) ShopeePay also sends asynchronous message via c allback URL (Notify transaction
status) to inform client backend regarding payment result
5) If no response from ShopeePay Server, Client can check transaction status by calling
ShopeePay Check Payment Status API
6) If Check Payment API returns:

14

a) Success - Payment process stops and user walks out of the store with purchase
b) Not found - Retry the payment process from the start
c) No response - continue retrying
i) Retry should be done at an incremental time range, at our recommended

retry timing at the following time marks:
(1) 5 seconds
(2) 10 seconds
(3) 15 seconds
(4) 20 seconds
(5) 25 seconds
.
.
.
(6) 100 seconds
7) After 100 seconds of retry with no response from ShopeePay, client can consider
payment transaction to have timed out.
8) If buyer can show evidence of payment success on their payment app, merchant can
choose to consider payment as successful and wait for reconciliation process on T+1 to
settle discrepancies if any.


15

4.1.3 API body
4.1.3.1 Create Dynamic QR API
Use this API to generate a dynamic QR code containing the payment amount and unique
payment reference ID.

● URL: "/v3/merchant-host/qr/create"
Request Parameters
Field Type Mandatory Description
request _id string Y Unique identifier for request
amount int64 Y Amount used for the payment, refer to

Parameters Specifications for specifics
currency string Y Refers to the currency abbreviation for the

transaction
● MYR
● IDR
● PHP
● SGD
merchant_ext_id string Y Unique identifier of merchant in client

system
store_ext_id string Y Unique identifier of store in client system
payment_reference_i string Y Unique identifier of transaction generated

d by client
qr_validity_period uint32 N If this field is filled, the QR code containing

the payment_reference_id in this request
will expire after the specified time period
(in seconds) and payment to this QR code
will fail.

If this field is not filled, default shopeepay
expiry time of 1200 seconds (20min) will
apply, from the time the request was
received.
terminal_id string N Unique identifier of store terminal

16

convenience_fee_ind string N Convenience fee can be fixed, or

icator percentage of the payment amount
● 01 - User inputs free amount
● 02 - Convenience fee is a fixed
value, to be indicated in
convenience_fee_fixed
● 03 - Convenience fee is based on
percentage of payment, to be
indicated in
convenience_fee_percentage
convenience_fee_fix int64 N Required if convenience fee is a fixed fee

ed as indicated by convenience fee indicator
convenience_fee_per uint32 N Required if convenience fee is percentage

centage as indicated by convenience fee indicator
additional_info string N Additional information will be in json

format.

Response Parameters
Field Type Description
request_id string Unique identifier for request
errcode int32 Error code to specify the error returned
debug_msg string Debug message to provide more information
store_name string Name of the store onboarded to shopeepay
qr_content string QR string in plaintext
qr_url string URL to download QR image, URL is valid for 5 minutes

Sample Request

17

Sample Response


18

4.1.3.2 Notify Transaction Status
Please refer to N
otify Transaction Status.

19

4.1.3.3 QR Invalidate API
Use this API to invalidate the payment reference in a QR code if the order in Client system is
closed/cancelled. Once QR is invalidated successfully, the QR code containing the payment
reference ID can no longer be used to make payment.

● URL: "/v3/merchant-host/qr/invalidate"
Request Parameters

system
payment_reference_id string Y Payment reference ID that corresponds

to the QR being invalidated

Response Parameters

Response Request

Response Response

20

4.1.3.4 Check Payment Status API
Please refer to C
heck Payment Status API
4.1.3.5 Create Refund API
Please refer to C
reate Refund API

21

4.2 Customer Presented Mode (CPM)

1) User have to click on “Pay” button as the entry point for CPM option in QR Offline
Payments, as shown in figure 4.2.1.
2) User is prompted to enter ShopeePay pin before showing the QR/barcode, as shown in
figure 4.2.2.
3) User QR is shown on ShopeePay, as shown in figure 4.2.3. Merchant scans user QR and
submits payment requests to ShopeePay system. User can choose to pay using
barcode, as shown in figure 4.2.4.
4) If payment is successful, User is shown the successful payment screen, as shown in
figure 4.2.5.
5) Payment Code expires when client does not scan User’s QR/barcode within the 1 minute
expiry time. User will have to click renew code and generate another Payment Code for
payment, as shown in figure 4.2.6.


22

Figure 4.2.1 User click on Figure 4.2.2 U

ser is Figure 4.2.3 U
ser CPM
“Pay” from Home Page prompted to enter ShopeePay QR/barcode is ready to be
pin scanned by merchant (1 min)

Figure 4.2.4 Switch to Figure 4.2.5 U

ser redirected Figure 4.2.6 P
ayment Code
barcode payment method to payment success page expired


23

1) User clicks on the “Pay” button on ShopeePay homepage to generate QR/barcode valid
for 1 minute
2) Cashier scans the user’s QR/barcode
3) Client calls Create CPM Payment API on ShopeePay Server with the transaction value
4) ShopeePay system returns the transaction result to client, and informs user of the
successful payment on ShopeePay App
5) If there’s no response from ShopeePay Server before request timeout (time out duration
is determined by Client), Client can check payment status by calling ShopeePay C
heck
Payment Status API
6) If C
heck Payment Status API returns:

24


retry timing at the following time mark:
● 5 seconds
● 10 seconds
● 15 seconds
● 20 seconds
.
.
.
● 100 seconds
7) After 100 seconds, payment transaction will timeout (ShopeePay will issue timeout on
that request) and the merchant should void the original payment transaction before
attempting payment creation again.
8) Calling Create Void API will return 2 status types:
a) Success - transaction successfully voided, user can try paying again.
b) Fail - transaction can be found but it does not meet the requirements for void
(same day 23:59 hours), merchant can try refund instead.
c) If the payment transaction is not found, or payment is still processing, calling

Calling Create Void API will return an error code (see Appendix 3 - Error Codes) to
indicate failure.
9) If the user making the payment can show evidence of payment success on their
payment app, merchant can choose to consider payment as successful and wait for
reconciliation process on T+1 to settle discrepancies if any.

25


26

4.2.3 APIs
4.2.3.1 Create CPM Payment
Use this API to initiate a payment request after scanning a user’s CPM QR.
● URL: "/v3/merchant-host/transaction/payment/create"
Request Parameters
amount uint64 Y Amount used for the payment, refer

to Parameters Specifications for
specifics

system
store_ext_id string Y Unique identifier of store in client

system
payment_code string Y Payment code is the QR/barcode

content from the user’s CPM QR code
payment_reference_id string Y Unique identifier of payment

transaction generated by client
mcc string Y Refers to Merchant Category Code,

refer to A
ppendix3 - Merchant
Category Code for suggestions
terminal_id string N Terminal ID refers to the Point of Sale

terminal in a store
terminal_ip string Y Terminal IP address refers to the IP

address of the merchant store
location
currency string Y Refers to the currency abbreviation

for the transaction
● MYR
● IDR
● PHP

27

● SGD

format.

Response Parameters
transaction_list object Will return Nil if transaction fails
● reference_id string Unique identifier of payment transaction

generated by client
● amount int64 Payment amount - inflated by a factor of 100
● create_time uint32 Create time of the individual transaction
● update_time uint32 Update time of the individual transaction
● transaction_sn string Wallet Transaction SN is the reference number

that is shown to the user.
● status uint32 Refer to Appendix 1C - Transaction Status for

specific transaction statuses
● transaction_type uint32 13 (Refer to Appendix 1A - Transaction Types for

specific transaction types)
● merchant_ext_id string Unique identifier of merchant in client system
● terminal_id string Terminal ID refers to the Point of Sale terminal in a

store
● user_id_hash string Used to identify the unique user
● store_ext_id string Unique identifier of store in client system


28

Sample Request
Sample Response

Please refer to C
4.2.3.3 Create Void API
Please refer to C
reate Void API
Please refer to C
reate Refund API

29

4.3 App-to-app Redirection (Jump App)

1) User selects ShopeePay as the payment method during checkout/purchase on the
Client’s application, as shown in Figure 4.3.1.
2) User clicks on the payment confirmation button in the Client’s application to confirm
they are paying with ShopeePay, as shown in Figure 4.3.2.
3) External application checks whether Shopee App is installed on user’s device.
a) If not, notify or redirect the user to install Shopee App first before completing
payment.
b) If yes, redirect the user to the ShopeePay payment amount page on Shopee app,
as shown in Figure 4.3.3.
4) Upon selecting payment options/vouchers in ShopeePay (if any), User enters their
ShopeePay PIN to proceed with the payment, as shown in figure 4.3.4.
5) If the payment is successful, User is shown the successful payment screen, as shown in
figure 4.3.5.
6) User can jump back to the original Client’s application and view their order status, as
shown in Figure 4.3.6. External application can then release the order to the user after
receiving notification of a successful payment from ShopeePay system.

30

Figure 4.3.1 User selects Figure 4.3.2 U

ser confirms Figure 4.3.3 Payment
ShopeePay as payment they are paying with Amount page
method ShopeePay

Figure 4.3.4 User is Figure 4.3.5 U

ser redirected Figure 4.3.6 C
lient’s app
prompted to enter pin to payment success page success page


31

1) After User creates an order on the Client’s app and confirms to pay by ShopeePay,
Client’s app calls O
rder Create API to get the redirect URLs to ShopeePay.
2) User clicks on the redirect URL to jump to ShopeePay payment screen. Before the user
is redirected to ShopeePay, the Client’s app should check if the user’s device has
Shopee App installed.

32

a) If the Shopee App is not installed, it is recommended that the Client app redirects
the user to install the shopee app using the r edirect_url_http link returned in O
rder
Create API, for an optimal user experience.
b) If Shopee App is installed, the Client’s app can direct the user to the ShopeePay
payment page.
3) ShopeePay app displays order details using payment identifier in redirect URL.
4) User checks the payment amount and inputs Shopeepay PIN to complete the payment.
5) ShopeePay system returns the transaction result and the user is redirected to payment
successful page. From the payment success page in ShopeePay, user can jump back to
the Client’s app using the return_url to view their order status.
[ Note ] Never use the redirect to return_url as an indication of payment success. Client
should only rely on server request/response to check the final status of payment.
6) ShopeePay sends the transaction status update via c allback URL (Notify transaction
status) to inform client backend regarding payment result. Client can also check
transaction status by calling the ShopeePay Check Payment Status API.
7) If Check Payment API returns:

retry timing at the following time marks:
(1) 5 seconds
(2) 10 seconds
.
.
.
(3) 30 seconds
8) After 30 seconds of retry with no response from ShopeePay, client can consider
payment transaction to have timed out. Differences can be settled during the T+1
reconciliation process with ShopeePay.

33

4.3.3 APIs
4.3.3.1 Create Order
Use this API to create a pending order to be paid by ShopeePay.
● URL: "/v3/merchant-host/order/create"
Request Parameters
request_id string Y Unique identifier of payment transaction

generated by client
payment_reference_id string Y Reference ID is the Store’s transaction

ID

system

system
amount int64 Y Amount used for the payment, refer to

currency string Y Refers to the currency abbreviation for

the transaction
● MYR
● IDR
● PHP
● SGD
return_url string Y Indicates the URL of the Client’s app to

redirect back to once payment has been
completed in ShopeePay.
Shopeepay accepts HTTP links and URL
scheme formats.
point_of_initiation string Y Value = “app” for App-to-app redirection
validity_period uint32 N If this field is filled, the order with the

corresponding payment_reference_id in
this request will expire after the
specified time period (in seconds) and

34

payment attempts to this

payment_reference_id will fail.

If this field is not filled, default
shopeepay expiry time of 1200 seconds
(20min) will apply, from the time the
request was received.

format.

Response Parameters
redirect_url_app string Returns an URL scheme to ShopeePay payment page.

Sample link:
shopeeid://main?apprl=%2Frn%2FTRANSFER_PAGE%3
Fnavigate_url%3Dhttps%253A%252F%252Fwallet.airpa
y.co.id%252Fwallet%252Fpay%253Ftoken%253D{paym
entToken}
redirect_url_http string Returns a universal link to ShopeePay payment page.

This link is recommended when the Client is unable to
implement a check for whether Shopee app is
installed on the user’s device before redirect.

Sample link:
https://wallet.airpay.co.id/universal-link/wallet/pay?de
ep_and_deferred=1&token=${paymentToken}

4.3.3.2 Notify Transaction Status
Please refer to N
otify Transaction Status


35

Please refer to C
4.3.3.4 Create Void API
Please refer to C
reate Void API
Please refer to C
reate Refund API

36

5. Common APIs
The Common API serves as the trivial API interface to be called for additional functions. Clients
can choose to integrate these functions based on their needs. The Common API includes Query
status, request void, create refund, set merchant, set store, get transactions
5.1 Notify Transaction Status

This request will send details of a successful payment to the Client server’s callback URL. This
URL is configured in ShopeePay system at time of onboarding, or sent in API requests.

Each callback request will contain a signature in the request header. This signature is generated
using the ShopeePay-issued secret key, assigned to the Client receiving the callback request.
The Client should use this signature to verify the authenticity of the callback content.

[ Note ] It is essential for the Client to validate that payment amount and payment_reference_id
matches the original /qr/create request before considering the payment as successful.

Callback Content
payment_reference_id string Unique identifier of payment transaction generated

by client
amount int64 Amount used for the payment, refer to P

arameters
Specifications for specifics
transaction_sn string Transaction identifier in ShopeePay system
payment_status uint32 Successful payment: payment_status = 1

Refer to Appendix 1B - Payment Status f or the
respective payment status
payment_method uint32 Indicates the payment method used. Refer to

Appendix 2 - Point of Initiation for the respective
payment methods
user_id_hash string Unique identifier of the user making the payment
merchant_ext_id string Unique identifier of the merchant in client’s system

37

store_ext_id string Unique identifier of the store in client’s system
terminal_id string Terminal id from the MPM QR code. This field will
be empty if the payment method is not MPM.

Sample Callback


38

5.2 Check Payment Status API

Use this API to query the status of a payment, and other information related to the payment.
● URL: "/v3/merchant-host/transaction/payment/check"
[ Note ] It is essential for the Client to validate that payment amount and payment_reference_id
matches the original /qr/create request before considering the payment as successful.
Request Parameters
request_id string Y Unique identifier of payment transaction

generated by client
payment_reference_id string Y Reference ID is the Store’s transaction

ID

system

system
amount int64 N This amount must match the original

payment amount

Response Parameters
payment_status uint32 Refer to Appendix 1B - Payment Status f or specific

statuses of payments
payment_method uint32 Indicates the payment method used. Refer to

Appendix 2 - Point of Initiation for the respective
payment methods

39

transaction_list object Will return empty list if no such transaction
● reference_id string Unique identifier of transaction generated by client.

This value should match the payment_reference_id
sent in the check status request.
● amount int64 Amount used for the payment, refer to P

arameters
● transaction_sn string Transaction serial number of the payment transaction

in ShopeePay
● status uint32 Refer to Appendix 1C - Transaction Status for specific

transaction statuses
● transaction_type uint32 Refer to Appendix 1A - Transaction Types f or specific

transaction types
● create_time uint32 Create time of the transaction
● update_time uint32 Update time of the transaction
● user_id_hash string Identifier for user that made the payment
● terminal_id string If terminal ID info exists in transaction

General Purpose of Check Payment Status
Merchants can only use the payment reference ID of payment transactions to check status.
Note: Any payment transaction check that returns status as refunded or void will have 2
transactions in transaction_list object, which will include:
❏ Transaction 1 - Payment transaction
❏ Transaction 2 - Refund or Void transaction
Refer to Appendix 1A - Transaction Types f or specific transaction types


40

Sample Request
Sample Response (Successfully paid transaction)

41

Sample Response (Refunded transaction)

42

5.3 Create Refund API

Use this API to request a refund of a successful payment, subject to refund conditions.
● URL: "/v3/merchant-host/transaction/refund/create"
● Valid Refund Period: 24 hours from time of payment
● Refund Type: Full Refund
Request Parameters
request_id string Y Unique identifier for request
payment_reference_i string Y Unique identifier of payment transaction

d generated by client
refund_reference_id string Y Unique identifier of refund transaction

generated by client

system

Response Parameters
● reference_id string Unique identifier of refund transaction

generated by client
● amount int64 Amount used for the payment, refer to


43

● transaction_sn string Transaction serial number of the refund

transaction in ShopeePay system
● transaction_type uint32 15 (Refer to Appendix 1A - Transaction Types

for specific transaction types)

Sample Request
Sample Response

44

5.4 Create Void API

Use this API to void a transaction if the Create Payment API does not return a conclusive result
on the status of the payment. Upon the success of the create void API call, the payment would
be void and the Client can choose to initiate another Create Payment request.
● URL: "/v3/merchant-host/transaction/void/create"
● Valid Void Period: Current day 23:59
Request parameters
payment_reference_id string This is the merchant’s payment reference ID
void_reference_id string This is the merchant’s void reference ID
merchant_ext_id string Unique identifier of merchant in client system
store_ext_id string Unique identifier of store in client system

Response Parameters
● reference_id string Unique identifier of refund transaction generated by

client
● amount int64 Amount used for the payment, refer to P

arameters
● transaction_sn string Transaction serial number of the void transaction in

ShopeePay system

45

● transaction_type uint32 15 (Refer to Appendix 1A - Transaction Types for

specific transaction types)

Sample Request
Sample Response


46

5.5 Set Merchant API

Use this API to create a Merchant in the ShopeePay system.
● URL: “/v3/merchant-host/merchant/set”
Structure: 1 Merchant - has many Stores (minimum 1 store)
Periodic Update: It is highly recommended for Clients to sync the latest Store information in
their system to ShopeePay, to ensure all users can enjoy a smooth payment experience at newly
added/updated Stores.
The following diagram represents the structure of Merchants and Stores in ShopeePay that ISVs
should adhere to during onboarding and sending payment requests. Payments are only
accepted on the Store level.
Request parameters
merchant_name string Y Name of the Merchant e.g. Starbucks

system
phone string N Merchant’s main phone number

47

email string N Merchant’s main email
logo string N Merchant’s logo, encoded in base64
postal_code string Y Merchant’s main postal code
city string Y Main city that Merchant operates in
state string N Main state that Merchant operates in
district string N Main district that Merchant operates in
ward string N Main ward that Merchant operates in
address string N Merchant’s main address
business_tax_id string N Business Tax ID used in that country
national_id_type uint32 N Type of identification. Refer to Appendix 4

- National Identity Type f or values to use
national_id string N National identity number
additional_info string N Additional information stored in JSON

string
mcc string Y Refers to Merchant Category Code, refer to

Appendix 3 - Merchant Category Code for
suggestions
point_of_initiation uint32 Y Method of QR Payment,

Refer to appendix A ppendix 2 - Point of
initiation for complete list of values to use
settlement_emails string N Emails to receive daily settlement report of

all Stores under the Merchant. For multiple
emails, separate by commas
withdrawal_option uint32 Y Withdraw to individual merchant’s bank

account = 1
Withdraw to Integration Parnter’s bank
account = 3
status uint32 N Status of Merchant

OK = 0
Banned = 4


48

Client can only move status from 0 to 4

and vice versa
Response Parameters
merchant object Merchant Entity
● merchant_name string Name of the Merchant e.g. Starbucks
● merchant_host_id uint32 Aggregator ID given by ShopeePay Server
● status uint32 Status of Merchant

Merchant OK = 0
Banned by ShopeePay = 1
Frozen by ShopeePay = 2
Deleted on ShopeePay = 3
Banned by Client via API = 4
● mcc string Merchant category code
● point_of_initiation uint32 Binary value of available POI values
● phone string Merchant’s main phone number
● email string Merchant’s main email
● postal_code string Merchant’s main postal code
● city string Merchant’s main city
● state string Merchant’s main state
● district string Merchant’s main district
● ward string Merchant’s main ward
● business_tax_id string Business Tax ID used in that country
● national_id_type uint32 National identity type
● national_id string National identity number

49

● additional_info string Additional information stored in JSON string
● withdrawal_option uint32 Merchant withdrawal option
extinfo object
● address string Merchant’s main address
● settlement_emails string Emails to receive daily settlement report
● withdrawal_option uint32 Withdrawal option of Merchant
● national_id_type uint32 National identity type
● national_id string National identity number
● business_tax_id string
● additional_info string Additional information relating to Store

Update Merchants’ Information
Clients can update information of previously added merchants via the Set Merchant API, using
“merchant_ext_id” as the identifier for each merchant.
Mandatory Field: merchant_ext_id
The only mandatory field is “merchant_ext_id”.
Fields that are not filled in in the Set Merchant API during updating will not be updated.
Fields that are mandatory during merchant onboarding cannot be updated to empty values.

50

5.6 Set store API

Use this API to create Stores for a Merchant in the ShopeePay system. A store has to be created
under a merchant before payment APIs c an be successfully called by that store.
● URL: “/v3/merchant-host/store/set”
Request parameters
store_name string Y Name of this store

system
status uint32 N Status of Store

OK = 0
Banned = 4

Client can only move status from 0 to 4
and vice versa
point_of_initiation uint32 Y Method of QR Payment, Refer to

appendix Appendix 2 - Point of initiation
for complete list of values to use
phone string N Phone number for this store
email string N Store’s email
logo string N Store’s logo, encoded in base64
address string N Address of the store
postal_code string Y The postal code that this store is

operating in
city string Y The city that this store operates in
state string N The state that this store operates in
district string N The district that this store operates in

51

ward string N The district that this store operates in, if
applicable
gps_longitude uint32 N Longitude coordinates of the store -

inflated by 100000
gps_latitude uint32 N Latitude coordinates of the store -

inflated by 100000
terminal_ids [ ] string N Point-of-Sale ID to identify every terminal

that a store has, comma separated
mcc string Y Refers to Merchant Category Code, refer

to Appendix3 - Merchant Category Code
for suggestions
nmid string N National merchant ID, applicable to

countries with QR interoperability (e.g. ID)
merchant_criteria string N Merchant Criteria

“UMI”: Micro merchant
“UKE”: Small merchant
“UME”: Medium merchant
“UBE”: Big merchant

Compulsory for ID
settlement_emails string N Emails to receive daily settlement report.

For multiple emails, separate by commas
additional_info string N Additional information stored in JSON

string

Response parameters
debug_msg string Debug message to provide more

information
store object Store Entity

52

● store_name string Store Name
● merchant_host_id uint32 Aggregator ID given by ShopeePay Server
● merchant_ext_id string Merchant External Identifier

Merchant ID given by aggregator
● store_ext_id string Store External Identifier

Aggregator issued store ID
● status uint32 Status of Store

Merchant OK = 0
Banned by ShopeePay = 1
Frozen by ShopeePay = 2
Deleted on ShopeePay = 3
Banned by Client via API = 4
● point_of_initiation uint32 Method of QR Payment,

Refer to appendix P
oint of initiation (POI)
values for complete list of values to use
● phone string Store’s phone number
● email string Store’s email
● postal_code string Store’s postal code
● city string Store’s city
● state string Store’s state
● district string Store’s district
● ward string Store’s ward, if applicable
● mcc string Refers to Merchant Category Code, refer

to Appendix3 - Merchant Category Code
for suggestions
● nmid string National merchant ID, applicable to

countries with QR interoperability (e.g. ID)
● merchant_criteria string Merchant criteria
● create_time uint32 Timestamp that the store was created
● update_time uint32 Timestamp that the store was updated

53

● gps_longitude uint32 Longitude coordinates of the store -

inflated by 100000
● gps_longitude uint32 Latitude coordinates of the store - inflated

by 100000
● store_id string Unique identifier of store by ShopeePay

system
extinfo object
● address string Address of the store
● settlement_emails string Emails to receive daily settlement report
● withdrawal_option uint32 Set to option 3 (withdraw to ISV bank

account) by default. Will follow Merchant
withdrawal option if different.
● merchant_criteria string Compulsory for QRIS in ID
● additional_info string Additional information relating to Store
● terminal_ids [ ] string List of terminal IDs under Store

Update Stores' Information
Clients can update information of previously added merchants via the Set Store API, using
“merchant_ext_id” and “store_ext_id as the identifier for each merchant.
Mandatory Field: merchant_ext_id, store_ext_id
The only mandatory fields are “merchant_ext_id” and “store_ext_id”. No other mandatory fields
are required for Update Stores’ Information. Fields that are not filled in in the Set Store API
during updating will not be updated.
Fields that are mandatory during store creation cannot be updated to empty values.

54

5.7 Get Transactions API

Use this API to retrieve the list of transactions for a certain time range, for purposes such as
reconciliation.
The maximum number of transactions returned for each API request is 5000. API requests
should be made multiple times in succession until the response body is empty, indicating that
all transactions within the time range have been returned.
For every new API request made within the specified time range, the request should indicate a
last_reference_id value, which is the reference_id of the last transaction returned in the response
of a previous API request.
The transactions will be returned in Descending order by update time (i.e. the latest transaction
will be returned first).
● URL: “/v3/merchant-host/transaction/list”
Request parameters
begin_time uint32 Y Filter transactions from the start of this time
end_time uint32 Y Filter transactions to the end of this time
last_reference_id string N The last transaction that was returned in the

previous API response
last_transaction_typ uint32 N The last transaction type (Appendix 1A -

e Transaction Types) that was returned in the
previous API response
transaction_type_list [ ] N Refer to Appendix 1A - Transaction Types

uint32 for specific transaction types
limit uint32 N The maximum number of transactions that

will be returned in each request. This value
should be within [1, 5000].
If this value is not filled, the latest 100
records will be returned by default.

55

Response Parameters
transaction_list object List of transactions
● reference_id string Reference ID is the merchant’s transaction ID

● amount int64 Amount used for the payment, inflated by a factor of 100
● transaction_sn string Wallet Transaction SN is the reference number that is

shown to the user
● status uint32 Refer to Appendix 1C - Transaction Status for specific

transaction statuses
● transaction_type uint32 Refer to Appendix 1A - Transaction Types f or specific

transaction types
● terminal_id string Terminal ID refers to the Point of Sale terminal in a store
● user_id_hash string Used to identify the unique user

56

Appendix
Appendix 1A - Transaction Types
Transaction type Value
Payment received 13
Refund sent 15
Void 26

Appendix 1B - Payment Status
Transaction status Value
Payment successful 1
Payment not found 2
Payment refunded 3
Payment void 4
Payment processing 5
Payment failed 6

Appendix 1C - Transaction Status
Transaction status Value
Transaction processing 2
Transaction successful 3
Transaction failed 4


57

Appendix 2 - Point of Initiation
POI methods offered Binary value Decimal value to indicate

during onboarding
MPM Static only 00001 1
MPM Dynamic only 00010 2
CPM only 00100 4
Deals only 01000 8
Jump App only 10000 16
MPM Static, MPM Dynamic 0011 3
MPM Static, CPM 0101 5
MPM Dynamic, CPM 0110 6
MPM Static, MPM Dynamic, CPM 0111 7
MPM Static, Deals 1001 9
MPM Dynamic, Deals 1010 10
MPM Static, MPM Dynamic, Deals 1011 11
CPM, Deals 1100 12
MPM Static, CPM, Deals 1101 13
MPM Dynamic, CPM, Deals 1110 14
MPM Static, MPM Dynamic, CPM, Deals 1111 15


58

Appendix 3 - Merchant Category Codes (MCC)

The following table contains some suggested MCC codes that can be assigned to Merchants
and Stores depending on the type of business.
Type of merchant MCC
Miscellaneous general merchandise stores 5399
Department stores 5411
Grocery stores, supermarkets 5411
Bakeries 5462
Miscellaneous food stores, convenience 5499

stores, markets, specialty stores, and
vending machines
Automotive parts, accessories stores 5533
Men’s and Boy’s clothing and accessories 5611

stores
Men’s and women’s clothing stores 5691
Miscellaneous accessory and apparel stores 5699
Equipment, furniture and home furnishing 5712

stores (excluding appliances)
Eating places, restaurants 5812
Fast food chains 5814
Drug stores and pharmacies 5912
Health and beauty shops 7298
Education services 8299
Charities, social services and government 8398

For other merchant category codes, clients may choose to take reference from the m
erchant
standards manual by Visa

59

Appendix 4 - National Identity Types
Country Value National identity type
ID 1 KTP
ID 2 KITAS
MY 1 IC
MY 2 Passport
SG 1 NRIC
SG 2 FIN


60

Appendix 5 - Error Codes
Value Description
-2 A server dropped the connection
-1 A server error occurred
0 Success
1 Request parameters error
2 Permission denied
4 Merchant/store not found
6 The user making the payment has not activated their wallet
7 Expired
9 User’s account is banned
11 Duplicate request/transaction
15 Payment amount exceeded limit
24 User's account is frozen
42 Insufficient balance
101 User wallet limit exceeded
103 User exceeded daily payment limit

Limit will reset the next day
105 Authorisation code is invalid
121 Client attempts to update completed transaction
126 User transaction limit reached
301 Invalid payment code or QR content

61

303 Merchant is trying to make payment to their own user account
304 Refund/void cannot be processed due to payment exceeding validity period.

Valid refund period is set at 24 hours by default.
305 Merchant invalid
601 Request to refund/void a payment transaction does not meet rules. This error
is also returned during refund block periods, set at midnight to 6am by default.
602 Request to refund/void a payment transaction is unsuccessful
Version control
Version Date Editor Remarks
V1.0 11.12.2019 G.Z. & J.L. Initial draft
V1.1 17.12.2019 G.Z. 1 - Add user_id_hash as unique identifier for user

paying to merchant
2 - Add currency indicator for amount
3 - Add amount inflation of 100
v1.2 3.1.2020 H.Y., Y.S. 1 - Remove “QRIS”

2 - Update set merchant/store API
V1.3 6.1.2020 G.Z. 1 - Update definition of user_id_hash

2 - Update definition and usage of terminal ID
3 - Add “district” and “ward” for onboarding
merchant and stores
V1.4 13.1.2020 Y.S., G.Z., 1 - Combine MPM and CPM integration

H.Y., J.L. documents
2 - Upgrade and rename all CPM and MPM
endpoints to v3
3 - Add refund transaction details in refund
response
4 - Add parameters in set merchant & set store
5 - Add qr_validity_period to /QR/create API
6 - Add support for QR Invalidate API
V1.45 10.2.2020 G.Z. 1 - Add new fields in /merchant/set and

/store/set/ APIs

62

2 - Add sample request and responses
V1.46 11.2.2020 H.Y. 1 - Update definition of withdrawal_option values
V1.47 28.2.2020 G.Z. 1- Specify values of transaction status in

appendix 1C
2- Specify link to appendix 1C for “status”
response parameter
V1.48 16.3.2020 G.Z. 1 - Add signature generation sample

2 - Add App-to-app redirection flow and API specs
3 - Add logo parameter to both merchant and
store
V1.49 26.5.2020 G.Z. 1 - Add details for essential fields to validate in
Check Status API request and Notify Transaction
Status callback
2 - Add time ranges where refund/void requests
are blocked for settlement processing
V1.50 27.5.2020 J.L. 1 - Added Signature Verification instructions
V1.51 22.6.2020 G.Z. 1 - Add “amount” parameter in check status API
V1.52 14.7.2020 G.Z. 1 - Update guidelines for the usage of Get

Transactions API
V1.53 05.8.2020 S.F., G.Z. 1 - Update error code mappings

2 - Add payment_method value in Notify
Transaction Status API
V1.54 12.10.2020 G.Z. 1 - Add payment_method value in Check Payment

Status API response

63

ShopeePay Payment API V1.54

Uploaded by

Copyright:

Available Formats

ShopeePay Payment API V1.54

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

ShopeePay Payment API V1.54

Uploaded by

Copyright:

Available Formats

4. Payment Method API 12

ShopeePay Payment APIs V1.54 ​ ​

4.2.3.4 Create Refund API 29

5. Common APIs 37

ShopeePay Payment APIs V1.54 ​ ​

This document is designed to be read in order.

1.2 Intended Audience

1.3 Version Control

ShopeePay Payment APIs V1.54 ​ ​

2.1 Payment Methods

3) App-to-app Redirect (Jump App)

ShopeePay Payment APIs V1.54 ​ ​

2.2 Term Definitions

Client Refers to the party making API calls

Store A shop at a physical location offering ShopeePay as a payment method

ShopeePay Payment APIs V1.54 ​ ​

ShopeePay Payment APIs V1.54 ​ ​

3.2 API Rules

3.2.1 Protocol Rules

Table 1: API formats and protocol rules

Transfer Mode HTTPS

Submit Mode POST Method

Date Format UNIX

Char Encoding UTF-8

Signature HMAC, SHA-256, Base64

ShopeePay Payment APIs V1.54 ​ ​

3.2.2 Parameter Specifications

3.2.2.1 Request Header

All requests will require this 2 parameters in the header

Client ID Unique identifier for caller, issued by ShopeePay

3.2.2.2 Payment Amount

Payment amount will be:

● Inflated by a factor of 100

● Smallest amount will be 001, which represents 0.01

● For currencies like IDR, that do not have denomination in cents, the smallest amount will

● IDR: Indonesia Rupiah

● MYR: Malaysia Ringgit

● PHP: Philippines Peso

● SGD: Singapore Dollar

ShopeePay Payment APIs V1.54 ​ ​

3.2.3 Security Specification

Python import hmac

Javascript let hash = CryptoJS.HmacSHA256(body, secret)

ShopeePay Payment APIs V1.54 ​ ​

Include the signature in the request

Perform the following steps to sign the message.

1. Extract the request body to be signed. For example:

{"request_id": "","store_ext_id": "externalstore","merchant_ext_id":

2. Hash the JSON content by using the SHA256 algorithm.

3.2.3.2 Signature Verification

ShopeePay Payment APIs V1.54 ​ ​

3.2.4 Access Nodes

Region Domain Suffix

Region Abbreviation Code

Indonesia ID co.id

Malaysia MY com.my

Philippines PH com.ph

Singapore SG sg

Append the region code to the end of the domain.

ShopeePay Payment APIs V1.54 ​ ​

ShopeePay Payment APIs V1.54

ShopeePay Payment APIs V1.54

ShopeePay Payment APIs V1.54

ShopeePay Payment APIs V1.54

ShopeePay Payment APIs V1.54

ShopeePay Payment APIs V1.54

ShopeePay Payment APIs V1.54

ShopeePay Payment APIs V1.54

ShopeePay Payment APIs V1.54

ShopeePay Payment APIs V1.54

ShopeePay Payment APIs V1.54

ShopeePay Payment APIs V1.54

Figure 4.1.1 Dynamic QR Figure 4.1.2 U

Figure 4.1.4 Enter PIN Figure 4.1.5 User redirected

ShopeePay Payment APIs V1.54

1) The client backend generates a QR code by calling ShopeePay system (Create

ShopeePay Payment APIs V1.54

ShopeePay Payment APIs V1.54

ShopeePay Payment APIs V1.54

ShopeePay Payment APIs V1.54

ShopeePay Payment APIs V1.54

ShopeePay Payment APIs V1.54

ShopeePay Payment APIs V1.54

ShopeePay Payment APIs V1.54

ShopeePay Payment APIs V1.54

Figure 4.2.1 User click on Figure 4.2.2 U

Figure 4.2.4 Switch to Figure 4.2.5 U

ShopeePay Payment APIs V1.54

ShopeePay Payment APIs V1.54

8) Calling Create Void API will return 2 status types: