Payment API Document

Version 1.65（WIP) - 20 Sep 2021

Table of Contents
Table of Contents 1

1. Introduction 4
1.1 About this Document 4
1.2 Intended Audience 4
1.3 Version Control 4

2. Definitions 5
2.1 Payment Methods 5
2.2 Term Definitions 6

3. System Requirements 7
3.1 Prerequisite 7
3.2 API Rules 8
3.2.1 Protocol Rules 8
3.2.2 Parameter Specifications 9
3.2.2.1 Request Header 9
3.2.2.2 Response Body 9
3.2.2.3 Transaction Amount 9
3.2.3 Security Specification 11
3.2.3.1 Signature 11
3.2.3.2 Signature Verification 12
3.2.4 Access Nodes 13

4. Payment Method API 14

4.1 Merchant Presented Mode (MPM) 14
4.1.1 User Payment Flow 14
4.1.2 Merchant Process 16
4.1.3 API body 18
4.1.3.1 Create Dynamic QR API 18
4.1.3.2 Notify Transaction Status 21
4.1.3.3 QR Invalidate API 22
4.1.3.4 Check Transaction Status API 23
4.1.3.5 Create Refund API [New] 23
4.2 Customer Presented Mode (CPM) 24
4.2.1 User Payment Flow 24

ShopeePay Payment APIs V1.65 1

 4.2.2 Merchant Process 26
4.2.3 APIs 28
4.2.3.1 Create CPM Payment 28
4.2.3.2 Check Transaction Status API 32
4.2.3.4 Create Refund API [New] 32
4.3 App-to-app Redirection (Jump App) 33
4.3.1 User Payment Flow 33
4.3.2 Merchant Process 35
4.3.3 APIs 36
4.3.3.1 Create Order 37
4.3.3.2 Notify Transaction Status 41
4.3.3.3 Order Invalidate API 41
4.3.3.4 Check Transaction Status API 43
4.3.3.6 Create Refund API [New] 43
4.4 Account Linking (Tokenized Payment) 44
4.4.1 User Link and Unlink Account Flow 44
4.4.2 User Direct Payment Flow 46
4.4.3 User Auth & Capture Flow 48
4.4.4 Merchant Link and Unlink Account Flow 50
4.4.5 Merchant Direct Payment Flow 52
4.4.6 Merchant Auth Capture Flow 54
4.4.7 APIs 55
4.4.7.1 Account Link 56
4.4.7.2 Get Access Token 58
4.4.7.3 Account Unlink 60
4.4.7.4 Get User Info 61
4.4.7.5 Get Redeemable Coin Value 63
4.4.7.6 Direct Payment 65
4.4.7.7 Create Auth 68
4.4.7.8 Reverse Auth 73
4.4.7.9 Capture 76
4.4.7.10 Create Refund API [New] 78
4.4.7.11 Check Transaction Status API 78
4.5. Ticket Linking 78
4.5.1 User Ticket Linking and Payment Flow 79
4.5.2 Merchant Process 80
4.5.3 APIs 83

ShopeePay Payment APIs V1.65 2

 4.5.3.1 Ticket Charge API 83
4.5.3.2 Check Transaction Status API 87
4.5.3.3 Create Refund API [New] 87
4.6. Cash In (Top Up) 88
4.6.1 User Cash In Flow (Top Up) 88
4.6.2 Merchant Process 90
4.6.2 API 91
4.6.2.1 Generate Cash In QR Code API 91
4.6.2.2 Cash In QR Invalidate API 94
4.6.2.3 Notify Transaction Status 95
4.6.2.4 Check Transaction Status API 95

5. Common APIs 97
5.1 Notify Transaction Status 97
5.2 Check Transaction Status API 100
5.3 Create Refund API [New] 105
5.4 Get Transactions API 109
5.5 Set Merchant API 110
5.6 Set store API 114

Appendix 118
Appendix 1A - Transaction Types 118
Appendix 1B - Payment Status 121
Appendix 1C - Transaction Status 122
Appendix 1D - Promotion Types 123
Appendix 2 - Point of Initiation 124
Appendix 3 - Merchant Category Codes (MCC) 125
Appendix 4 - National Identity Types 125
Appendix 5 - Error Codes 128
Version Control 129

ShopeePay Payment APIs V1.65 3

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.

ShopeePay Payment APIs V1.65 4

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) Account Linking Mode (Tokenized Payment)

The user will perform a one-time authentication and authorization to successfully link
ShopeePay on the external platform. An access token will be issued by ShopeePay and used by
the external platform for a fast and seamless payment experience in the future.

5) Ticket Linking Mode

The client generates a physical ticket that will be passed to the user, which contains information
of the service provided by the client. The user will perform a one-time authorization to link their
ShopeePay account to the ticket via scanning the ticket. Clients will be able to make a one-time
ticket payment charge to the user’s ShopeePay account for the linked ticket within a certain
period after ticket linking.

Note: Ticket Linking Mode is currently only available in Indonesia.

ShopeePay Payment APIs V1.65 5

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.

This value is only available for countries ID, MY, PH, SG

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.

ShopeePay Payment APIs V1.65 6

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.

ShopeePay Payment APIs V1.65 7

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

ShopeePay Payment APIs V1.65 8

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 Response Body

The ShopeePay API response body is in JSON format.

● Parameters can be returned in random sequence

● Additional parameters may be returned in future without advance notice from

ShopeePay

Client system’s logic should not assume that the order of arrangement of response parameters
or the total number of parameters returned will remain constant throughout time.

3.2.2.3 Transaction Amount

Transaction amount will be:

● Integer format

● Inflated by a factor of 100

Example:

● Smallest amount will be 1, which represents 0.01

● For currencies like IDR and VND, that do not have denomination in cents, the smallest
amount will be 100, which represents 1 IDR (Rp 1) and 1 VND (₫ 1).

There will not be a default currency. The current supported currency will be:

ShopeePay Payment APIs V1.65 9

 ● IDR: Indonesian Rupiah

● MYR: Malaysian Ringgit

● PHP: Philippine Peso

● SGD: Singapore Dollar

● THB: Thai Baht

● VND: Vietnamese Dong

ShopeePay Payment APIs V1.65 10

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. Code
implementation using some common programming languages is listed below for your
reference. You could check the implementation in more programming languages at this public
docs.

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))
}

ShopeePay Payment APIs V1.65 11

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

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: pz148x0gXyPCLHxnlhEydNLg55jni91i

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.

ShopeePay Payment APIs V1.65 12

 3. Signatures from steps #1 and #2 must be identical. If they are different, the response
should not be trusted.

ShopeePay Payment APIs V1.65 13

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

Thailand TH co.th

Vietnam VN vn

Append the region code to the end of the domain.

Environment Domain

sandbox api.uat.wallet.airpay.<region>

live api.wallet.airpay.<region>

ShopeePay Payment APIs V1.65 14

4. Payment Method API
Payment Method APIs refers to APIs that are used specifically for certain payment methods.
Currently there are four payment methods: Merchant Presented Mode (MPM), Customer
Presented Mode (CPM), App-to-app Redirection (Jump App) and Account Linking Mode
(Tokenized Payment).

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.

ShopeePay Payment APIs V1.65 15

 Figure 4.1.1 Dynamic QR Figure 4.1.2 User scan QR Figure 4.1.3 Check payment
generated by cashier code on ShopeePay amount

Figure 4.1.4 Enter PIN Figure 4.1.5 User redirected

to payment success page

ShopeePay Payment APIs V1.65 16

ShopeePay Payment APIs V1.65 17
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 callback 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 Transaction Status API

6) If Check Transaction Status API returns:

ShopeePay Payment APIs V1.65 18

 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.

ShopeePay Payment APIs V1.65 19

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 this 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
● THB
● VND

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.
Accepts up to 25 characters.

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.

ShopeePay Payment APIs V1.65 20

 If this field is not filled, default shopeepay
expiry time of 1200 seconds (20min) will
apply, from the time the request was
received. Maximum validity period is 3600
seconds (60 min).
Note: this field is only applicable in ID, MY,
PH, SG.

expiry_time uint32 N Unix timestamp

If this field is filled, the QR code containing

the payment_reference_id in this request
will expire and payment that QR code will
fail after the specified timestamp.

If this field is not filled, default shopeepay

expiry time of 1200 seconds (20min) will
apply, from the time the request was
received.

Note: this field is only applicable in TH, VN.

terminal_id string N Unique identifier of store terminal

Accepts up to
- 25 characters in ID, MY, PH, SG
- 20 characters in TH, VN

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

Note: This field is temporarily unavailable

in Thailand and Vietnam. Reserved for
future usage.

convenience_fee_fix int64 N Required if convenience fee is a fixed fee

ed as indicated by convenience fee indicator

ShopeePay Payment APIs V1.65 21

 Note: This field is temporarily unavailable
in Thailand and Vietnam. Reserved for
future usage.

convenience_fee_per uint32 N Required if convenience fee is percentage

centage as indicated by convenience fee indicator

Note: This field is temporarily unavailable

in Thailand and Vietnam. Reserved for
future usage.

promo_ids string N Comma separated eligible promo_ids of

100 characters or less (up to 20), if any.
These promo_ids will be checked against
promotional campaigns configured in
ShopeePay to determine the valid reward
amount the user can receive for this
transaction.

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

ShopeePay Payment APIs V1.65 22

Sample Response

4.1.3.2 Notify Transaction Status

Please refer to Notify Transaction Status.

ShopeePay Payment APIs V1.65 23

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

Field Type Mandatory Description

request _id string Y Unique identifier for request

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_id string Y Payment reference ID that corresponds

to the QR being invalidated

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.

Response Request

Response Response

ShopeePay Payment APIs V1.65 24

4.1.3.4 Check Transaction Status API

Please refer to Check Transaction Status API

4.1.3.5 Create Refund API [New]

Please refer to Create Refund API [New]

ShopeePay Payment APIs V1.65 25

4.2 Customer Presented Mode (CPM)

4.2.1 User Payment Flow

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.

See screenshots on the following page for the front-end user flow on ShopeePay.

ShopeePay Payment APIs V1.65 26

 Figure 4.2.1 User click on Figure 4.2.2 User is prompted Figure 4.2.3 User CPM
“Pay” from Home Page to enter ShopeePay pin QR/barcode is ready to be
scanned by merchant (1 min)

Figure 4.2.4 Switch to Figure 4.2.5 User redirected Figure 4.2.6 Payment Code
barcode payment method to payment success page expired

ShopeePay Payment APIs V1.65 27

ShopeePay Payment APIs V1.65 28
4.2.2 Merchant Process

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 transaction status by calling Check
Transaction Status API

6) If Check Transaction Status API returns:

a) Success - Payment process stops and user walks out of the store with purchase

ShopeePay Payment APIs V1.65 29

 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 mark:

● 5 seconds

● 10 seconds

● 15 seconds

● 20 seconds

● 100 seconds

7) After 100 seconds, payment transaction will timeout (ShopeePay will issue a timeout on
that request) and the merchant should refund the original payment transaction before
attempting payment creation again.

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

a) Success - transaction successfully refunded, user can try paying again.

b) Fail - transaction can be found but it does not meet the requirements for refund,
merchant can try again at a later time.

c) If the payment transaction is not found, or payment is still processing, calling

Calling Create Refund API will return an error code (see Appendix 5 - 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.

ShopeePay Payment APIs V1.65 30

ShopeePay Payment APIs V1.65 31
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

Field Type Mandatory Description

request _id string Y Unique identifier for request

amount uint64 Y Amount used for the payment, refer to

Parameters Specifications for
specifics

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_code string Y Payment code is the QR/barcode

content from the user’s CPM QR
code.
If there’s no national QR code
standard defined on a national level,
this code starts with “918” and
contains 20 digits.

payment_reference_id string Y Unique identifier of transaction

generated by client

expiry_time uint32 N Unix timestamp.

If this field is filled, the order with the

corresponding payment_reference_id
in this request will fail after the
specified timestamp.

If this field is not filled, default

ShopeepPay expiry time of 120

ShopeePay Payment APIs V1.65 32

 seconds (2min) will apply for this
payment method, from the time the
request was received.

Note: this field is temporarily

unavailable in ID, MY, PH, SG.

terminal_id string N Terminal ID refers to the Point of Sale

terminal in a store

currency string Y Refers to the currency abbreviation

for the transaction
● MYR
● IDR
● PHP
● SGD
● THB
● VND

promo_ids string N Comma separated eligible promo_ids

of 100 characters or less (up to 20), if
any.
These promo_ids will be checked
against promotional campaigns
configured in ShopeePay to
determine the valid reward amount
the user can receive for this
transaction.

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

transaction_list* object Will return Nil if transaction fails

● reference_id string Unique identifier of payment transaction

generated by client

ShopeePay Payment APIs V1.65 33

 ● 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

co_funding object Will return empty if no co-funding involved

Note: this field is temporarily not available in ID,

MY, PH, SG

● promotion_ext_na string Name of the promotion for client’s reference

me

● redeemed_promot int64 Amount of the promotion benefit obtained by user

ion_amount
Note: for refund transaction types, this will be the
amount of promotion benefit ShopeePay
clawbacks from the user in that refund transaction

Refer to Parameters Specifications for specifics

● redeemed_promot uint32 Refer to Appendix 1D - Promotion Types for

ion_type specific transaction types

● co_funding_cost_ int64 Amount of cost born by merchant for the

ShopeePay Payment APIs V1.65 34

 amount promotion benefit

Note: for refund transaction types, this will be the

amount of co-funding amount that the client will
no longer be charged for due to that refund
transaction
Refer to Parameters Specifications for specifics

*[Note]: in Thailand and Vietnam, the name of object “transaction_lis”’ is returned as

“transaction”.

Sample Request

ShopeePay Payment APIs V1.65 35

Sample Response

4.2.3.2 Check Transaction Status API

Please refer to Check Transaction Status API

4.2.3.4 Create Refund API [New]

Please refer to Create Refund API [New]

ShopeePay Payment APIs V1.65 36

4.3 App-to-app Redirection (Jump App)

4.3.1 User Payment Flow

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 sees the successful payment screen, as shown in
Figure 4.3.5.

6) User jump backs 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.

See screenshots on the following page for the front-end user flow on ShopeePay.

ShopeePay Payment APIs V1.65 37

 Figure 4.3.1 User selects Figure 4.3.2 User confirms Figure 4.3.3 Payment Amount
ShopeePay as payment they are paying with page
method ShopeePay

Figure 4.3.4 User is prompted Figure 4.3.5 User redirected Figure 4.3.6 Client’s app
to enter pin to payment success page success page

ShopeePay Payment APIs V1.65 38

4.3.2 Merchant Process

1) After User creates an order on the Client’s app and confirms to pay by ShopeePay,
Client’s app calls Order 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.

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 redirect_url_http link returned in Order
Create API, for an optimal user experience.

ShopeePay Payment APIs V1.65 39

 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 callback URL (Notify transaction
status) to inform the Client about the payment result.

7) Client can also call Check Transaction Status API to check the payment status.

8) If Check Transaction API returns:

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

.
.
.

(5) 30 seconds

9) 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.

ShopeePay Payment APIs V1.65 40

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

Field Type Mandatory Description

request_id string Y Unique identifier for request

payment_reference_id string Y Unique identifier of transaction

generated by client

merchant_ext_id string Y Unique identifier of merchant in client

system

store_ext_id string Y Unique identifier of store in client system

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
● THB
● VND

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.

platform_type string Y This indicates the type of the Client’s

platform that the user triggered the jump
app flow from.

ShopeePay Payment APIs V1.65 41

 Accepted values:
● “app”
● “pc”
● “mweb” (mobile web)

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
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. Maximum validity
period is 3600 seconds (60 min).

Note: this field is only applicable in ID,

MY, PH, SG.

expiry_time uint32 N Unix timestamp

If this field is filled, the order with the

corresponding payment_reference_id in
this request will expire after the
specified timestamp and 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.

Note: this field is only applicable in TH,

VN.

promo_ids string N Comma separated eligible promo_ids of

100 characters or less (up to 20), if any.
These promo_ids will be checked
against promotional campaigns

ShopeePay Payment APIs V1.65 42

 configured in ShopeePay to determine
the valid reward amount the user can
receive for this transaction.

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.

redirect_url_app string Returns an URL scheme to ShopeePay payment page.

Sample link:
shopeeid://main?apprl=%2Frn%2FTRANSFER_PAGE
%3Fnavigate_url%3Dhttps%253A%252F
%252Fwallet.airpay.co.id%252Fwallet%252Fpay
%253Ftoken%253D{paymentToken}

Note: This field is temporarily unavailable in Thailand

and Vietnam.

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?
deep_and_deferred=1&token=${paymentToken}

Sample Request

ShopeePay Payment APIs V1.65 43

Sample Response

[ Note ] In Thailand and Vietnam, when ShopeePay redirects user back to the return_url provided
in the Client’s API request, the following parameters may be appended in the return_url. Client
may utilize such information to display some preliminary results to users on front end.

Example: https://www.google.com/?
amount=2000&client_id=11000193&reference_id=Test_returnURL_03&result_code=100&signatu
re=hw8FvuV1oVLTNuII7Xafawfqv1BGZsceeTpzo%3D&transaction_sn=1007011238

Field Type Mandatory Description

amount string Y Amount used for the payment, refer to

Parameters Specifications for specifics

client_id string Y Unique identifier to identify the caller;

issued by ShopeePay

reference_id string Y Unique identifier of payment transaction

ShopeePay Payment APIs V1.65 44

 generated by client

Same value as the

“payment_reference_id” in the request

result_code string Y Preliminary status of the payment order

for Client’s front-end display only.

[ Note ] Never take this as an indication

of actual payment status. Client should
only rely on server request/response to
check the final status of payment.

Enumerations:
- 100: payment success
- 201: payment cancelled but the
redirection_url is still usable
- 202: payment failed
- 203: payment still in processing
- 204: payment expired

transaction_sn string N Transaction identifier in ShopeePay

system. Only returned when a
transaction is created in ShopeePay
system.

signature string Y Encrypted signature of the above

parameters using the Secret Key. Client
should verify the signature first before
consuming any parameters above.

Base64.URLEncoding applies here, using

the Secret issued by ShopeePay

4.3.3.2 Notify Transaction Status

Please refer to Notify Transaction Status

ShopeePay Payment APIs V1.65 45

4.3.3.3 Order Invalidate API

Use this API to invalidate the existing order payment reference id for the pending order in the
Client system if it is closed/cancelled. Once the order payment reference id is invalidated
successfully, the corresponding “redirect_url_app” and “redirect_url_http” can no longer be used
to make payment.

● URL: "/v3/merchant-host/order/invalidate"

Request Parameters

Field Type Mandatory Description

request _id string Y Unique identifier for request

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_id string Y Payment reference ID that corresponds

to the order being invalidated

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.

Sample Request

ShopeePay Payment APIs V1.65 46

Sample Response

4.3.3.4 Check Transaction Status API

Please refer to Check Transaction Status API

4.3.3.6 Create Refund API [New]

Please refer to Create Refund API [New]

ShopeePay Payment APIs V1.65 47

4.4 Account Linking (Tokenized Payment)

4.4.1 User Link and Unlink Account Flow

1) User links their ShopeePay account to the Client’s application during checkout/purchase
on the Client’s application, as shown in Figure 4.4.1.

2) If User has not logged in yet, User will be redirected to login page, as shown in Figure
4.4.2. (Note: Login page UI in Thailand and Vietnam are slightly different)

3) After login, User is redirected to the ShopeePay Agreement Page to authorise the linking,
as shown in Figure 4.4.3.

4) User enters their ShopeePay PIN, as shown in Figure 4.4.4.

5) User sees the result of the account linking on the ShopeePay application and/or Client’s
application, as shown in Figure 4.4.5.

6) Upon successful account linking, User receives a push notification from

ShopeePay/Shopee App, as shown in Figure 4.4.6.

7) User can unlink ShopeePay via the Client’s platform or via the ShopeePay/Shopee App,
as shown in Figure 4.4.7 and Figure 4.4.8 respectively.

8) Once the ShopeePay account is unlinked, User is not able to access ShopeePay from the
Client’s platform anymore.

Note: if Client in Indonesia, Malaysia, Philippines or Singapore requires phone number match,
the linking flow will be slightly different: Agreement Page -> PIN Verification -> OTP Verification

See screenshots on the following page for the front-end user flow.

ShopeePay Payment APIs V1.65 48

 Figure 4.4.1 User chooses to Figure 4.4.2 User logins first Figure 4.4.3 User gives
link ShopeePay if not logged in the web yet consent on Agreement page

Figure 4.4.4 User enters PIN Figure 4.4.5 User sees the Figure 4.4.6 User receives a
to verify result of the account linking push notification upon
successful linking

ShopeePay Payment APIs V1.65 49

 Figure 4.4.7 User can unlink Figure 4.4.8 User can unlink
ShopeePay account via from the Client’s platform via
Client’s App ShopeePay/Shopee App

4.4.2 User Direct Payment Flow

1) User chooses to pay with the linked ShopeePay account on the Client’s platform, as
shown in Figure 4.4.9.

2) User may be prompted with ShopeePay PIN verification again, as shown in Figure 4.4.10.

3) If the payment is successful, User will see a payment success page on the Client’s
platform, as shown in Figure 4.4.11.

Note: the PIN verification process during Direct Payment is currently not applicable to Thailand
and Vietnam.

See screenshots on the following page for the front-end user flow.

ShopeePay Payment APIs V1.65 50

 Figure 4.4.9 User pays with Figure 4.4.10 User may be Figure 4.4.11 Client’s
linked ShopeePay account prompted with Shopeepay platform payment success
PIN re-authentication page

ShopeePay Payment APIs V1.65 51

4.4.3 User Auth & Capture Flow

1) User pays with the linked ShopeePay account on the Client’s platform, as shown in
Figure 4.4.12.

2) User may be prompted with ShopeePay PIN verification again, as shown in Figure 4.4.13.

3) If auth (fund reservation) is successful, User will see a push notification in

ShopeePay/Shopee App, as shown in Figure 4.4.14.

4) If capture (actual payment) is successful after auth, User will receive another push
notification in ShopeePay/Shopee App, as shown in Figure 4.4.15.

5) If a refund is initiated and processed, User will receive a push notification in

ShopeePay/Shopee App, as shown in Figure 4.4.16.

Note: Auth and Capture flow is temporarily not available in Thailand and Vietnam.

See screenshots on the following page for the front-end user flow.

Figure 4.4.12 User pays with Figure 4.4.13 User may be Figure 4.4.14 Push
linked ShopeePay prompted with PIN re- notification for successful
authentication fund reservation

ShopeePay Payment APIs V1.65 52

 Figure 4.4.15 Push Figure 4.4.16 Push
notification for the final notification for successful
successful payment refund

ShopeePay Payment APIs V1.65 53

4.4.4 Merchant Link and Unlink Account Flow

1) After User chooses to link their ShopeePay account, Client calls the Account Link API to
kick start the linking process.

a) If the user’s phone number is passed in the request, ShopeePay checks internally
if the phone number belongs to a valid ShopeePay user and returns a web URL
for Client to redirect the user to.

2) Client redirects User to the ShopeePay agreement page. User reads and consents to the
permissions required by the Client, and completes both ShopeePay PIN and OTP
verification. After successful verification, User is redirected to the Client’s page as
indicated in the ’return_url’ in the Account Link API request along with an auth code.

ShopeePay Payment APIs V1.65 54

 3) Client’s frontend passes the auth code to the Client’s server and exchanges for a
ShopeePay access token by calling the Get Access Token API.

4) If User chooses to unlink ShopeePay, Client calls the Account Unlink API to invalidate the
ShopeePay access token.

a) If the access token is invalidated successfully, User is not able to access

ShopeePay from the Client’s platform anymore.

ShopeePay Payment APIs V1.65 55

4.4.5 Merchant Direct Payment Flow

1) During the checkout/payment process on Client’s frontend

a) If Client wants to display the redeemable Shopee coins value to the User:

i) Client can call Get Redeemable Coin Value API to get a maximum coin
redemption percentage allowed; OR

ii) Client can pass “payment_amount” in the request of the Maximum

Redeemable Coin API call. The response will indicate the exact number of
coins User can spend in this payment, and the exact remaining amount to
be paid using ShopeePay.

b) If Client does not need to display the redeemable Shopee coins value to the User:

i) Client can call Direct Payment API to initiate a direct charge. A redirect url
to the ShopeePay PIN verification page may be returned if this verification

ShopeePay Payment APIs V1.65 56

 is required. (Note: this PIN verification process currently is not applicable
to Thailand and Vietnam)

2) ShopeePay sends the transaction status update via callback URL (Notify transaction
status) to inform the Client about the payment result.

3) Client can also call Check Transaction Status API to check the payment status.

ShopeePay Payment APIs V1.65 57

4.4.6 Merchant Auth Capture Flow

Auth capture flow is useful for merchants (e.g. Ride hailing apps) that want to reserve a user's
fund first and only deduct either a full or partial amount later.

1) User expresses intent to make a purchase (e.g. attempts to book a taxi via a ride hailing
app)

a) Client calls Create Auth API to reserve the estimated amount to be charged. After
successful fund reservation, client can inform the user that they can successfully
proceed to the next step (e.g. client app informs the user that their booking for
the taxi is successful.

b) Once the user has received the product/service (e.g. after a taxi ride is complete),
client calls Capture API to collect the final payment amount (e.g.deduct the final

ShopeePay Payment APIs V1.65 58

 taxi trip fare). Any amount reserved during Auth but not collected in the final
payment capture will be returned to the user after capture is successfully
processed.

2) If user exits the purchase process (e.g. cancels the taxi booking before the ride begins),
Client can call Reverse Auth API to release the funds reserved during Auth.

3) Similar to the direct payment flow, ShopeePay sends the transaction status update via
callback URL (Notify transaction status) to inform the client about the payment result.

4) Client can also call Check Transaction Status API to check the payment status.

Note: Auth and Capture flow is temporarily not available in Thailand and Vietnam.

ShopeePay Payment APIs V1.65 59

4.4.7 APIs

4.4.7.1 Account Link

Use this API to kick start the account linking process of a ShopeePay account to your platform

● URL: "/v3/merchant-host/account/link"

Request Parameters

Field Type Mandatory Description

request_id string Y Unique identifier for each account linking

request.

return_url string Y The URL for ShopeePay's front-end to

redirect to after User completes
verification on ShopeePay.
For a normal web URL which starts with
‘http’ or ‘https’, ShopeePay client will
open it with the default browser.
For others (for example,
some_app://xxxxx), ShopeePay client
will try to open the app registered with
the schema.

Note: Only web page URLs are accepted

for countries ID, MY, PH, SG.
Any valid schema is accepted for
countries TH, VN.

linking_reference_id string O Unique identifier in Client’s system to

identify this linking.

Note:
- Client is strongly encouraged to
pass in this value for better
tracking and identification
purposes.
- This field is currently only
available in TH, VN.

ShopeePay Payment APIs V1.65 60

 merchant_ext_id string Y Unique identifier of merchant in client
system

phone string N Registered phone number of the user on

Client’s platform.

This field is required if Client wants to

restrict the user to link a ShopeePay
account with the same registered phone
number.

Note: please input a phone number with

the country code, e.g., for a VN phone
number “0981234567”, it shall be
passed in as ‘84981234567” in this field

platform_type string N This indicates the type of the Client’s

platform that the user triggered the
account linking flow from.

Accepted values:
● “app”
● “pc”
● “mweb” (mobile web)
● “qr” (for scan QR linking)

Note: “qr’ enumeration is currently only

available in TH VN

Response Parameters

Field Type Description

request_id string The same value as the `request_id` in the request.

errcode int32 Error code to specify the error returned.

debug_msg string Debug message to provide more information.

redirect_url_web string ShopeePay web URL for the merchant's front-end to

redirect to.
If Client wants to restrict the user to link a ShopeePay

ShopeePay Payment APIs V1.65 61

 account with the same registered phone number,
Client must use this redirect URL to reduce cases of
account linking failure due to mismatched phone
number.

redirect_url_qr string URL to download a QR image for users to use

ShopeePay App to scan and perform linking on App

Note: this field is currently only available in TH, VN

Sample Request

Sample Response

4.4.7.2 Get Access Token

Use this API to get a ShopeePay access token using auth code returned in the account linking
step.

● URL: "/v3/merchant-host/access-token/get"

Request Parameters

Field Type Mandatory Description

request_id string Y Unique identifier for request

linking_reference_id string C Unique identifier in Client’s system to

identify this linking, same as what is
used in the Account Link API.

ShopeePay Payment APIs V1.65 62

 Either linking_reference_id or auth_code
should be provided in the request, but
Client is strongly encouraged to use
linking_refernece_id for better tracking
and identification purposes.

Note: this field is currently only available

in TH, VN

auth_code string C The auth code is returned by ShopeePay

when user is redirected to the ‘return_url’
specified by Client in Account Link API.
Client should call Get Access Token as
soon as auth code is received. Auth
code will expire after 15 mins.

Either linking_reference_id or auth_code

should be provided in the request.

Sample Link:
www.isv-integrator.com/payment?
authCode=AQhTc89wVeKkDUX91jCVAg
Yf6swAydVH&result=100&ticket=bvhmj3
lq1clggb75u9n0pkndu

some_app://{redirect_page}?
authCode=AQhTc89wVeKkDUX91jCVAg
Yf6swAydVH&result=100

Note: the auth_code appended in

return_url is url-encoded and has to be
decoded first to be used as the request
parameter in this API.

Result codes
100 - User authentication success
201 - User cancelled linking
202 - Account linking failed

Note: 201 and 202 are not applicable to

TH, VN.

ShopeePay Payment APIs V1.65 63

Response Parameters

Field Type Description

request_id string The same value as the `request_id` in the request.

errcode int32 Error code to specify the error returned.

debug_msg string Debug message to provide more information.

access_token string The access token used to identify the ShopeePay

account to be linked.

The access token is only valid for 5 years. User need

to manually re-link the account after the token expires.

user_id_hash string Unique identifier for a ShopeePay user.

linking_reference_id string Unique identifier in Client’s system to identify this

linking

Note: this field is currently only available in TH, VN.

merchant_ext_id string Unique identifier of merchant in client system

Note: this field is currently only available in TH, VN.

linking_status int32 Status of this linking

1 - Active
2 - Inactive (could be reverted back to Active)
3 - Invalid

Note: this field is currently only available in TH, VN.

create_time string Create time of this individual linking

Note: this field is currently only available in TH, VN.

update_time string Update time of this individual linking

Note: this field is currently only available in TH, VN.

ShopeePay Payment APIs V1.65 64

Sample Request

Sample Response

ShopeePay Payment APIs V1.65 65

4.4.7.3 Account Unlink

Use this API to unlink a ShopeePay account from a User’s account on your platform.

● URL: "/v3/merchant-host/account/unlink"

Request Parameters

Field Type Mandatory Description

request_id string Y Unique identifier for request.

access_token string Y The access token used to identify a

ShopeePay user’s account.

Response Parameters

Field Type Description

request_id string The same value as the `request_id` in the request.

errcode int32 Error code to specify the error returned.

debug_msg string Debug message to provide more information.

Sample Request

Sample Response

ShopeePay Payment APIs V1.65 66

4.4.7.4 Get User Info

Use this API to get a user’s ShopeePay account information for display purposes.

● URL: "/v3/merchant-host/user-info/get"

Request Parameters

Field Type Mandatory Description

request_id string Y Unique identifier for request.

access_token string C The access token used to identify the

user account.

Either linking_reference_id or
access_token should be provided in the
request.

linking_reference_id string C Unique identifier in Client’s system to

identify this linking, same as what is
used in the Account Link API.

Either linking_reference_id or
access_token should be provided in the
request.

Note: this field is currently only available

in TH, VN

Response Parameters

Field Type Description

request_id string The same value as the `request_id` in the request.

errcode int32 Error code to specify the error returned.

● User_info will not be returned if user’s account
status is deleted or banned.
● User_info will be returned per normal if user’s
account status is frozen.

debug_msg string Debug message to provide more information.

linking_info object Linking information. Will only be returned if there is an

ShopeePay Payment APIs V1.65 67

 linking found with the linking_reference_id or
acess_token provided

Note: this field is currently only available in Thailand

and Vietnam

linking_reference_id string Unique identifier in Client’s system to identify this

linking

Note: this field is currently only available in TH, VN.

linking_status int32 Status of this linking

1 - Active
2 - Inactive (could be reverted back to Active)
3 - Invalid

Note: this field is currently only available in TH, VN.

user_info object Will return empty if the ShopeePay account is banned

or deleted.

Note: this field is currently not available in Thailand

and Vietnam

● phone_number string Masked phone number of the user’s linked

ShopeePay account.
Example: ********1234

Note: this field is currently not available in Thailand

and Vietnam

● wallet_balance int64 Value inflated by 100.

Note: this field is currently not available in Thailand

and Vietnam

● coin_balance int64 Value inflated by 100.

Only available if user allow coin redemption for their

account

Note: this field is currently not available in Thailand

and Vietnam

ShopeePay Payment APIs V1.65 68

 ● kyc_passed boolean True - User passed KYC
False - User has not passed KYC yet

Note: this field is currently not available in Thailand

and Vietnam

Sample Request

Sample Response

ShopeePay Payment APIs V1.65 69

4.4.7.5 Get Redeemable Coin Value

Use this API to get the user's maximum redeemable coin amount in percentage or in absolute
amount.

● URL: "/v3/merchant-host/coin/potential-redemption"

Note: This API is temporarily unavailable for use in Thailand and Vietnam.

Request Parameters

Field Type Mandatory Description

request_id string Y Unique identifier for request.

access_token string Y The access token used to identify the

user account.

payment_amount int64 N Payment amount value inflated by 100.

Pass this field if Client wants to display
the exact amount of redeemable coins
for a specific payment.

Response Parameters

Field Type Description

request_id string The same value as the `request_id` in the request.

errcode int32 Error code to specify the error returned

debug_msg string Debug message to provide more information

max_coin_percentage int64 Maximum percentage of the payment can be paid for

using coins.

potential_payment_amo int64 Estimated payment amount to be paid with ShopeePay

unt after coin redemption. Value inflated by 100.
This value is returned if “payment_amount” is sent in
the request.

potential_coin_amount int64 Maximum numbers of coins can be used in the

payment. Value inflated by 100.
This value is returned if “payment_amount” is sent in
the request.

ShopeePay Payment APIs V1.65 70

Sample Request

Sample Response

ShopeePay Payment APIs V1.65 71

4.4.7.6 Direct Payment

Use this API to initiate a direct payment with an access token.

● URL: "/v3/merchant-host/transaction/payment/direct"

Request Parameters

Field Type Mandatory Description

request_id string Y Unique identifier for request.

payment_reference_id string Y Unique identifier of payment transaction

generated by client

merchant_ext_id string Y Unique identifier of merchant in client

system

store_ext_id string Y Unique identifier of store in Client

system

access_token string Y The access token used to identify the

user’s ShopeePay account.

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
● THB
● VND

return_url string Y Indicates the URL of the Client’s

platform to redirect back to, once
payment verification on ShopeePay (if
applicable) is done.

use_coin boolean N Users may indicate their preference to

use or not to use coins to offset their
payment on the Client’s platform. Use

ShopeePay Payment APIs V1.65 72

 this field to pass the user's preference.
● True: attempt to use coins
● False: do not use coins

Note: This field is temporarily

unavailable in Thailand and Vietnam.
Reserved for future usage.

promo_ids string N Comma separated eligible promo_ids of

100 characters or less (up to 20), if any.
These promo_ids will be checked
against promotional campaigns
configured in ShopeePay to determine
the valid reward amount the user can
receive for this transaction.

Note: This field is temporarily

unavailable in Thailand and Vietnam.
Reserved for future usage.

order_reference_id string N Unique identifier of the order in the

Client’s system. This will help
ShopeePay to identify all transactions
created for the same product/service
user purchases.
For example, in auth capture flow, if the
final payment amount is larger than
what has been reserved in auth
transaction, client may choose to
capture the current auth in full and
create another payment transaction to
charge the user the remaining amount.
In this case, “order_reference_id” passed
in Create Auth API and Direct Payment
API should be the same.

additional_info string N Additional information will be in json

format.

Response Parameters

Field Type Description

ShopeePay Payment APIs V1.65 73

 request_id string The same value as the `request_id` in the
request.

errcode int32 Error code to specify the error returned.

debug_msg string Debug message to provide more information.

redirect_url string The URL for the Client’'s front-end to redirect

to for PIN verification. Only applicable if PIN
verification is needed.

transaction object Will return Nil if transaction failed

● reference_id string Unique identifier of payment transaction

generated by Client.

Same value as the “payment_reference_id” in

the request.

● amount int64 Amount used for the payment, refer to

Parameters Specifications for specifics

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

specific transaction statuses

● transaction_type uint32 1003 (Refer to Appendix 1A - Transaction

Types for specific transaction types)

● transaction_sn string Transaction identifier in ShopeePay system

● create_time uint32 Create time of the individual transaction

● update_time uint32 Update time of the individual transaction

● user_id_hash string Identifier for user that made the payment

● merchant_ext_id string Unique identifier of merchant in Client system

● store_ext_id string Unique identifier of store in Client system

ShopeePay Payment APIs V1.65 74

Sample Request

Sample Response 1 (when ShopeePay PIN verification is not required)

Sample Response 2 (when ShopeePay PIN verification is required, not applicable to TH/VN)

ShopeePay Payment APIs V1.65 75

4.4.7.7 Create Auth

Use this API to create an auth transaction to reserve funds for subsequent capture.

● URL: "/v3/merchant-host/transaction/auth/create"

Note: This API is temporarily unavailable for use in Thailand and Vietnam.

Request Parameters

Field Type Mandatory Description

request_id string Y Unique identifier for request.

auth_reference_id string Y Unique identifier of authorisation

transaction generated by client

merchant_ext_id string Y Unique identifier of merchant in client

system

store_ext_id string Y Unique identifier of store in Client

system

access_token string Y The access token used to identify the

user account.

amount int64 Y Amount to be reserved during auth, refer

to Parameters Specifications for
specifics

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

platform to redirect back to once
payment verification on ShopeePay (if
applicable) is done.

use_coin boolean N Users may indicate their preference to

use or not to use coins to offset their
payment on the Client’s platform Use

ShopeePay Payment APIs V1.65 76

 this field to pass the user's preference.
● True: attempt to use coins
● False: do not use coins

auth_expiry_time uint32 N Unix timestamp. The value represents

when this auth transaction will expire.
Maximum expiry time is 14 days from
the time the request is received by
ShopeePay.

If no value is passed, the expiry time of

an auth is by default 24 hours from the
time the request is received by
ShopeePay.

promo_ids string N Comma separated eligible promo_ids of

100 characters or less (up to 20), if any.
These promo_ids will be checked
against promotional campaigns
configured in ShopeePay to determine
the valid reward amount the user can
receive for this transaction.

order_reference_id string N The reference ID to indicate the order in

the Client’s system. This will help
ShopeePay to identify all transactions
created for the same product/service
user purchases.
For example, in auth capture flow, if the
final payment amount is larger than
what has been reserved in auth
transaction, client may choose to
capture the current auth in full and
create another payment transaction to
charge user the remaining amount. In
this case, “order_reference_id” passed in
Create Auth API and Direct Payment API
should be the same.

ShopeePay Payment APIs V1.65 77

Response Parameters

Field Type Description

request_id string The same value as the `request_id` in the request.

errcode int32 Error code to specify the error returned.

debug_msg string Debug message to provide more information.

redirect_url string The URL for the Client’'s frontend to redirect to for
PIN verification, valid for 30 mins. Only applicable if
PIN verification is needed.

transaction object Will return empty if no such transaction

● reference_id string Unique identifier of auth transaction generated by

client.

Same value as the “auth_reference_id” in the request.

● amount int64 Amount used for the payment, refer to Parameters

Specifications for specifics

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

transaction statuses

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

specific transaction types)

● create_time uint32 Create time of the individual transaction

● update_time uint32 Update time of the individual transaction

● user_id_hash string Identifier for user that made the payment

● merchant_ext_id string Unique identifier of merchant in Client system

● store_ext_id string Unique identifier of store in Client system

ShopeePay Payment APIs V1.65 78

ShopeePay Payment APIs V1.65 79
Sample Request

Sample Response

ShopeePay Payment APIs V1.65 80

4.4.7.8 Reverse Auth

Use this API to reverse funds reserved previously using an auth request.

● URL: "/v3/merchant-host/transaction/auth/reverse"

Note: This API is temporarily unavailable for use in Thailand and Vietnam.

Request Parameters

Field Type Mandatory Description

request_id string Y Unique identifier for request.

reverse_auth_reference string Y Unique identifier of authorisation

_id reversal transaction generated by
client

merchant_ext_id string Y Unique identifier of merchant in

client system.

store_ext_id string Y Unique identifier of store in client

system.

auth_reference_id string Y The ‘reference_id’ of the auth

transaction Client wants to reverse.

Response Parameters

Field Type Description

request_id string The same value as the `request_id` in the request.

errcode int32 Error code to specify the error returned.

debug_msg string Debug message to provide more information.

transaction object Will return empty if no such transaction

● reference_id string Unique identifier of auth reversal transaction

generated by client.

Same value as the “reverse_auth_reference_id” in

the request.

ShopeePay Payment APIs V1.65 81

 ● amount int64 Amount used for the payment, refer to
Parameters Specifications for specifics

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

specific transaction statuses

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

for specific transaction types)

● create_time uint32 Create time of the individual transaction

● update_time uint32 Update time of the individual transaction

● user_id_hash string Identifier for user that made the payment

● merchant_ext_id string Unique identifier of merchant in Client system

● store_ext_id string Unique identifier of store in Client system

ShopeePay Payment APIs V1.65 82

Sample Request

Sample Response

ShopeePay Payment APIs V1.65 83

4.4.7.9 Capture

Use this API to create a full or partial capture transaction using funds reserved from the
corresponding auth transaction. Capture must be requested before the auth transaction
expires. Only one partial capture will be accepted for each auth transaction..

● URL: "/v3/merchant-host/transaction/auth/capture"

Request Parameters

Field Type Mandatory Description

request_id string Y Unique identifier for request.

capture_reference_id string Y Unique identifier of capture transaction

generated by client

merchant_ext_id string Y Unique identifier of merchant in client

system.

store_ext_id string Y Unique identifier of store in client

system.

amount int64 Y The amount to capture. Capture amount

should be no greater than the original
auth amount.

auth_reference_id string Y The ‘auth_reference_id’ of the auth

transaction Client wants to capture.

Response Parameters

Field Type Description

request_id string The same value as the `request_id` in the request.

errcode int32 Error code to specify the error returned.

debug_msg string Debug message to provide more information.

transaction object Will return empty if no such transaction

● reference_id string Unique identifier of capture transaction generated by

client.

Same value as the `capture_reference_id` in the

ShopeePay Payment APIs V1.65 84

 request.

● amount int64 Amount used for the payment, refer to Parameters

Specifications for specifics

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

transaction statuses

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

specific transaction types)

● transaction_sn string Transaction identifier in ShopeePay system

● create_time uint32 Create time of the individual transaction

● update_time uint32 Update time of the individual transaction

● user_id_hash string Identifier for user that made the payment

● merchant_ext_id string Unique identifier of merchant in Client system

● store_ext_id string Unique identifier of store in Client system

ShopeePay Payment APIs V1.65 85

Sample Request

Sample Response

4.4.7.10 Create Refund API [New]

Please refer to Create Refund API [New]

4.4.7.11 Check Transaction Status API

Please refer to Check Transaction Status API

ShopeePay Payment APIs V1.65 86

4.5. Ticket Linking
4.5.1 User Ticket Linking and Payment Flow

Ticket Linking has a similar concept to CPM flow.

1) User obtains the physical ticket (containing QR or Barcode) from the client.

2) User clicks on “Scan” icon on Shopee/ShopeePay homepage and scan the QR code, as

shown in figure 4.5.2

3) If the ticket is valid, User can verify the ticket details and select vouchers and coins

redemption (if any), as shown in figure 4.5.3

4) User inputs ShopeePay PIN to confirm the ticket linking, as shown in figure 4.5.4

5) If the linking is successful, User will see the successful linking result, as shown in figure

4.5.5

6) User passes the ticket to the cashier when requested, and the ticket will be charged by

the cashier to User’s ShopeePay account

7) If payment is successful, User will be able to check their transaction history and see the

successful payment screen, as shown in figure 4.5.6.

See screenshots below for the front-end user flow on ShopeePay

ShopeePay Payment APIs V1.65 87

 Figure 4.5.1 User receives Figure 4.5.2 User proceeds to Figure 4.5.3 User will see the
the Partner generated ticket scan the ticket ticket detail page

Figure 4.5.4 PIN Verification Figure 4.5.5 Successful Figure 4.5.6 Successful
for the User after confirming linking page deduction of ticket payment.
ticket details.

ShopeePay Payment APIs V1.65 88

4.5.2 Merchant Process

ShopeePay Payment APIs V1.65 89

 1) Client generates the ticket based on pre-aligned protocols with ShopeePay

2) User will scan the ticket generated by Client, and ShopeePay will call Client's endpoint to
validate the Ticket.

3) User will be redirected to the ticket detail page and configure the ticket linking.

4) After User confirms their configurations, ShopeePay will require User to verify
ShopeePay PIN first and call Client to confirm this linking action

5) After Client responds ‘Success’ to ShopeePay, Shopeepay will redirect to the linking
successful page

6) The cashier will request for the physical ticket from the User to process the payment,
and the Client will call the ticket charge API when the cashier receives the ticket to do
payment deduction from user’s ShopeePay account

7) If there’s no response from ShopeePay Server before request timeout (time out duration
is determined by Client), Client can check transaction status by calling Check
Transaction Status API

8) If Check Transaction Status API returns:

a) Success - Payment has succeeded

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 mark:

● 5 seconds

● 10 seconds

● 15 seconds

● 20 seconds

ShopeePay Payment APIs V1.65 90

 ● 100 seconds

9) After 100 seconds, payment transaction will timeout (ShopeePay will issue a timeout on
that request) and the merchant should refund the original payment transaction before
attempting payment creation again.

10) Calling Create Refund [New] API will return 2 status types:

a) Success - transaction successfully refunded, user can try paying again.

b) Fail - transaction can be found but it does not meet the requirements for refund,
merchant can try again at a later time.

c) If the payment transaction is not found, or payment is still processing, calling

Calling Create Refund [New] API will return an error code (see Appendix 5 - Error
Codes) to indicate failure.

ShopeePay Payment APIs V1.65 91

4.5.3 APIs

4.5.3.1 Ticket Charge API

Use this API to initiate a payment request after scanning the User's ticket.

● URL: "/v3/merchant-host/transaction/ticket/charge”

Note: this API is currently only available in Indonesia.

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

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_code string Y Unique identifier of the linking for the

specific user and ticket. (refNumber)

ticket string Y The ticket code generated by the

client

payment_reference_id string Y Unique identifier of payment

transaction generated by client

expiry_time uint32 N Unix timestamp.

If this field is filled, the order with the

corresponding payment_reference_id
in this request will fail after the
specified timestamp.

If this field is not filled, default

ShopeePay expiry time of 120

ShopeePay Payment APIs V1.65 92

 seconds (2min) will apply for this
payment method, from the time the
request was received.

currency string Y Refers to the currency abbreviation

for the transaction
● MYR
● IDR
● PHP
● SGD
● THB
● VND

promo_ids string N Comma separated eligible promo_ids

of 100 characters or less (up to 20), if
any.
These promo_ids will be checked
against promotional campaigns
configured in ShopeePay to
determine the valid reward amount
the user can receive for this
transaction.

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

transaction 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

ShopeePay Payment APIs V1.65 93

 ● 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

ShopeePay Payment APIs V1.65 94

Sample Request

Sample Response

4.5.3.2 Check Transaction Status API

Please refer to Check Transaction Status API

4.5.3.3 Create Refund API [New]

Please refer to Create Refund [New] API

ShopeePay Payment APIs V1.65 95

4.6. Cash In (Top Up)

4.6.1 User Cash In Flow (Top Up)

Cash In has a similar User Flow as User Payment Flow (MPM)

1) User pays cash to the merchant. The Cash amount paid to the merchant includes the
topup amount and transaction fees charged by the merchant for the transaction.

2) Merchant checks that the cash amount received from User is correct.

3) Merchant generates dynamic QR code containing the Top Up amount, as shown in

Figure 4.6.1.

4) User goes to ShopeePay Homepage to click on either “Scan” or “Top Up” as shown in
Figure 4.6.2.

a) If User clicks on “Top Up” icon on ShopeePay homepage, they can select the top
up via QR scan option, as shown in Figure 4.6.3.

b) If User clicks on “Scan” icon on ShopeePay homepage, they will be directed to

the scanner page, as shown in Figure 4.6.4

5) User checks all details are correct, and presses the “Top Up” button to complete the
topup, as shown in figure 4.6.5.

6) If the cash in is successful, User sees the successful top up screen, as shown in Figure
4.6.6.

Note: This flow is not applicable in Thailand and Vietnam.

See screenshots below for the front-end user flow on ShopeePay for Cash In

ShopeePay Payment APIs V1.65 96

 Figure 4.6.1 Dynamic QR Figure 4.6.2 Figure 4.6.3
generated by cashier User ShopeePay Homepage ShopeePay Top Up

Figure 4.6.4 User scan QR Figure 4.6.5 Figure 4.6.6

code on ShopeePay Top Up Confirmation Page Transaction Success Page

ShopeePay Payment APIs V1.65 97

4.6.2 Merchant Process

1) The client backend generates a QR code by calling ShopeePay system (Generate Cash In
QR Code API) and displays it to the user to be scanned

2) The user scan the QR code, checks Cash In (Top Up) amount and transaction fee to
proceed with the Cash In

3) ShopeePay system returns the Cash In (Top Up) result to the user and the user is
redirected to the Cash In (Top Up) successful page.

4) ShopeePay also sends asynchronous message via callback 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 Transaction Status API

6) After 100 seconds of retry with no response from ShopeePay, client can consider Cash
In (Top Up) transaction to have timed out.

ShopeePay Payment APIs V1.65 98

 7) If buyer can show evidence of Cash In success/failure on their mobile app, merchant can
choose to consider Cash In as successful and wait for the reconciliation process on T+1
to settle discrepancies, if any.

Note: This flow is not applicable in Thailand and Vietnam.

4.6.2 API

4.6.2.1 Generate Cash In QR Code API

Use this API to generate a dynamic QR code containing the top up amount and unique payment
reference ID.

● URL: "/v3/merchant-host/cash-in/qr/create”

Note: This API is not applicable in Thailand and Vietnam.

Request Parameters

Field Type Mandato Description

ry

request_id string Y Unique identifier of payment transaction

generated by client

cashin_reference_id string Y Reference ID is the Store’s transaction ID

merchant_ext_id string Y Unique identifier of merchant in client

system

store_ext_id string Y Unique identifier of store in client system

amount uint32 Y The amount that the user wants to Cash In

(Top Up) excluding the transaction fee, refer
to Parameters Specifications for specifics

currency string Y Refers to the currency abbreviation for the

transaction
● MYR
● IDR
● PHP
● SGD

ShopeePay Payment APIs V1.65 99

 qr_validity_period uint32 N If this field is filled, the cash in (top up)
corresponding cashin_reference_id in this
request will expire after the specified time
period (in seconds) and cash in attempts
using this cashin_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.

terminal_id string N Unique identifier of store terminal

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

qr_content string QR string in plaintext

qr_url string URL to download QR image, URL is valid for 5 minutes

store_name string Name of the store onboarded to shopeepay

cico_fee int64 Cash In transaction fee

Sample Request

Sample Response

ShopeePay Payment APIs V1.65 100

ShopeePay Payment APIs V1.65 101
4.6.2.2 Cash In QR Invalidate API

Use this API to invalidate a Cash In QR Code generated previously by Client. Once QR is
invalidated successfully, the QR code containing the payment reference ID can no longer be
used to make Cash In transactions.

● URL: "/v3/merchant-host/cash-in/qr/invalidate”

Note: This API is not applicable in Thailand and Vietnam.

Request Parameters

Field Type Mandatory Description

request_id string Y Unique identifier of payment transaction

generated by client

merchant_ext_id string Y Unique identifier of merchant in client

system

store_ext_id string Y Unique identifier of store in client system

cashin_reference_id string Y Reference ID is the Store’s transaction ID

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

ShopeePay Payment APIs V1.65 102

Sample Request]

Sample Response

4.6.2.3 Notify Transaction Status

Please refer to Notify Transaction Status

4.6.2.4 Check Transaction Status API

Please refer to Check Transaction Status APIP

ShopeePay Payment APIs V1.65 103

ShopeePay Payment APIs V1.65 104
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, create refund, set merchant, set store, get transactions

5.1 Notify Transaction Status

This request will send details of a transaction result 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.

Multiple repeated notifications might be sent to the Client and Client shall be able to handle the
repeated notifications with same contents properly.

[ 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.

Common Fields

Field Type Description

amount int64 Amount of the transaction, refer to Parameters

Specifications for specifics

transaction_sn string Transaction identifier in ShopeePay system

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

ShopeePay Payment APIs V1.65 105

 store_ext_id string Unique identifier of the store in client’s system

terminal_id string Terminal id in merchant’s MPM/CPM API request.

This field will be empty if the payment flow is not
MPM or CPM.

co_funding object Will return empty if no co-funding involved

Note: this object is temporarily unavailable in ID, MY,

PH, SG

● promotion_ext_ string Name of the promotion for client’s reference

name

● redeemed_prom int64 Amount of the promotion benefit obtained by user

otion_amount
Note: for refund transaction types, this will be the
amount of promotion benefit ShopeePay clawbacks
from the user in that refund transaction

Refer to Parameters Specifications for specifics

● redeemed_prom uint32 Refer to Appendix 1D - Promotion Types for specific

otion_type transaction types

● co_funding_cos int64 Amount of cost born by merchant for the promotion

t_amount benefit

Note: for refund transaction types, this will be the

amount of co-funding amount that the client will no
longer be charged for due to that refund transaction

Refer to Parameters Specifications for specifics

For ID, MY, PH, SG: Additional Fields For Transactions that are not part of Account Linking
APIs

Field Type Description

payment_reference_id string Unique identifier of payment transaction generated

by client

ShopeePay Payment APIs V1.65 106

 payment_status uint32 Successful payment: payment_status = 1
Refer to Appendix 1B - Payment Status for the
respective payment status

For ID, MY, PH, SG: Additional Fields For Transactions that are part of Account Linking APIs

Callbacks for transactions related to Account Linking (i.e. Payment Authorization, Payment
Capture, Authorization Reversal, Direct Payment) will contain the following fields.

For TH, VN: Additional Fields for All Payment Transactions

Field Type Description

reference_id string A new field introduced to generalise the notify

callback for all types of transactions. This could be
either payment_reference_id or
capture_reference_id.

transaction_type uint32 A new field introduced to generalise the notify

callback for all types of transactions.
Refer to Appendix 1A - Transaction Types for
specific transaction types

transaction_status uint32 A new field introduced to generalise the notify

callback for all types of transactions.
Refer to Appendix 1C - Transaction Status for
specific transaction statuses

Response Parameters
Note: in Thailand and Vietnam, if Client does not respond with code = 0, ShopeePay will resend
notifications up to 2 times.

Field Type Mandatory Description

errcode int32 Y Error code to specify the error

returned
- 0: success

debug_msg string N Debug message to provide more

information

ShopeePay Payment APIs V1.65 107

Sample Callback For Transactions that are not part of Account Linking APIs

Sample Callback For Transactions that are part of Account Linking APIs

ShopeePay Payment APIs V1.65 108

5.2 Check Transaction Status API
Use this API to query the status of a transaction across all supported transaction types.

● URL: "/v3/merchant-host/transaction/check"

If Check Transaction Status API returns:

1) Success - payment process stops and Client can mark this transaction as success.
2) Not found - retry the payment process from the start
3) No response - continue retrying
a) Retry should be done at an incremental time range, at our recommended retry
timing at the following time marks:
i) 5 seconds
ii) 10 seconds

.
.
.

vi) 30 seconds
4) 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.

[ Note ] This API is an upgraded version of previous Check Payment Status API to support
transaction status inquiry for all transaction types including Auth, Capture and Auth Reversal.

Request Parameters

Field Type Mandatory Description

request_id string Y Unique identifier of the request.

reference_id string Y Unique identifier of the transaction client

would like to query, which could be
payment_reference_id,
capture_reference_id or
refund_reference_id.

transaction_type uint32 Y Transaction type of the transaction

ShopeePay Payment APIs V1.65 109

 client would like to query.
Refer to Appendix 1A - Transaction
Types for specific transaction types.

merchant_ext_id string Y Unique identifier of merchant in client

system

store_ext_id string Y Unique identifier of store in client system

amount int64 Y This amount must match the original

transaction amount

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

payment_method uint32 Indicates the payment method used. Refer to

Appendix 2 - Point of Initiation for the respective
payment methods

transaction object Will return empty if no such transaction

● reference_id string Unique identifier of transaction generated by client.

This value should match the reference_id sent in the
request, which could be payment_reference_id,
capture_reference_id or refund_reference_id.

● amount int64 Amount of the transaction, inflated by a factor of 100.

Refer to Parameters Specifications for specific
inflation method

● transaction_sn string Transaction serial number of the transaction in

ShopeePay.

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

transaction statuses

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

ShopeePay Payment APIs V1.65 110

 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

● merchant_ext_id string Unique identifier of merchant in client system

● store_ext_id string Unique identifier of store in client system

● terminal_id string If terminal ID info exists in transaction

● promo_id_applied string promo_id applied to the payment transaction. This will

be filled only if the user received a reward from a valid
promotion with the promo_id specified.

Note: this field is temporarily unavailable in TH, VN

co_funding object Will return empty if no co-funding involved

Note: this object is temporarily unavailable in ID, MY,

PH, SG

● promotion_ext_na string Name of the promotion for client’s reference

me

● redeemed_promot int64 Amount of the promotion benefit obtained by user

ion_amount
Note: for refund transaction types, this will be the
amount of promotion benefit ShopeePay clawbacks
from the user in that refund transaction

Refer to Parameters Specifications for specifics

● redeemed_promot uint32 Refer to Appendix 1D - Promotion Types for specific

ion_type transaction types

● co_funding_cost_ int64 Amount of cost born by merchant for the promotion

amount benefit

Note: for refund transaction types, this will be the

amount of co-funding amount that the client will no

ShopeePay Payment APIs V1.65 111

 longer be charged for due to that refund transaction

Refer to Parameters Specifications for specifics

Sample Request

Sample Response

ShopeePay Payment APIs V1.65 112

5.3 Create Refund API [New]
Use this upgraded create refund API to request a refund of a successful transaction, subject to
refund conditions.

● URL: "/v3/merchant-host/transaction/refund/create-new"

● Valid Refund Period: 1-365 days

● Refund Types: Full refund only for SG; Partial refund supported for ID, MY, PH TH, VN.

Request Parameters

Field Type Mandatory Description

request_id string Y Unique identifier for request

reference_id string Y Unique identifier of transaction

generated by client. This can be either
“payment_reference_id ” or
“capture_reference_id” passed to
ShopeePay when payment/capture was
created.

transaction_type uint32 Y Refer to Appendix 1A - Transaction

Types for specific transaction types.
Eligible transaction types for refund are:
● Payment
● Payment captured
● Direct payment

refund_reference_id string Y Unique identifier of refund transaction

generated by client

merchant_ext_id string Y Unique identifier of merchant in client

system

store_ext_id string Y Unique identifier of store in client

system

amount int64 Y Amount of the refund transaction.

Note:

ShopeePay Payment APIs V1.65 113

 Refer to Parameters Specifications for
specifics.

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.

transaction object Will return empty list if no such transaction

● reference_id string Unique identifier of refund transaction

generated by client

● amount int64 Amount of the refund transaction, refer to

Parameters Specifications for specifics

● transaction_sn string Transaction serial number of the refund

transaction in ShopeePay system

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

specific transaction statuses

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

for specific transaction types)

● create_time uint32 Create time of the individual transaction

● update_time uint32 Update time of the individual transaction

● user_id_hash string Identifier for user that made the payment

● merchant_ext_id string Unique identifier of merchant in client system

● store_ext_id string Unique identifier of store in client system

● terminal_id string If terminal ID info exists in transaction

co_funding object Will return empty if no co-funding involved

Note: this object is temporarily unavailable in

ShopeePay Payment APIs V1.65 114

 ID, MY, PH, SG

● promotion_ext_na string Name of the promotion for client’s reference

me

● redeemed_promo int64 Amount of the promotion benefit obtained by

tion_amount user

Note: for refund transaction types, this will be

the amount of promotion benefit ShopeePay
clawbacks from the user in that refund
transaction

Refer to Parameters Specifications for

specifics

● redeemed_promo uint32 Refer to Appendix 1D - Promotion Types for

tion_type specific transaction types

● co_funding_cost_ int64 Amount of cost born by merchant for the

amount promotion benefit

Note: for refund transaction types, this will be

the amount of co-funding amount that the
client will no longer be charged for due to that
refund transaction

Refer to Parameters Specifications for

specifics

ShopeePay Payment APIs V1.65 115

Sample Request

Sample Response

ShopeePay Payment APIs V1.65 116

5.4 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”

Note: This API is temporarily unavailable for use in Thailand and Vietnam.

Request parameters

Field Type Mandatory Description

request_id string Y Unique identifier for request

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_type uint32 N The last transaction type (Appendix 1A -

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

ShopeePay Payment APIs V1.65 117

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

Response Parameters

Field Type Description

errcode int32 Error code to specify the error returned.

debug_msg string Debug message to provide more information.

transaction_list object List of transactions

● reference_id string Reference ID is the unique identifier of the transaction

generated by the client.

● amount int64 Amount used for the payment, 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 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

● promo_id_applied string promo_id applied to the payment transaction. This will

be filled only if the user received a reward from a valid
promotion with the promo_id specified.

ShopeePay Payment APIs V1.65 118

5.5 Set Merchant API
Use this API to create a Merchant in the ShopeePay system.

● URL: “/v3/merchant-host/merchant/set”

Note: This API is only available in Philippine and Malaysia based on ShopeePay operational
requirements.

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
integration partners should adhere to during onboarding and sending payment requests.
Payments are only accepted on the Store level.

Request parameters

Field Type Mandatory Description

request_id string Y Unique identifier for request

merchant_name string Y Name of the Merchant e.g. Starbucks

Maximum character length: 50 characters,

ShopeePay Payment APIs V1.65 119

 including blank spaces

merchant_ext_id string Y Unique identifier of merchant in client

system

phone string N Merchant’s main phone number

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 for 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 Appendix 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

ShopeePay Payment APIs V1.65 120

 Withdraw to Integration Partner’s bank
account = 3

status uint32 N Status of Merchant

OK = 0
Banned = 4

Client can only move status from 0 to 4

and vice versa

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.

merchant object Merchant Entity

● merchant_name string Name of the Merchant e.g. Starbucks

● merchant_host_id uint32 Aggregator ID given by ShopeePay Server

● merchant_ext_id string Unique identifier of merchant in client system

● 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

ShopeePay Payment APIs V1.65 121

 ● 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

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.

ShopeePay Payment APIs V1.65 122

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 can be successfully called by that store.

● URL: “/v3/merchant-host/store/set”

Note: This API is only available in Philippine and Malaysia based on ShopeePay operational
requirements.

Request parameters

Field Type Mandatory Description

request_id string Y Unique identifier for request

store_name string Y Name of this store (max. 25 characters)

merchant_ext_id string Y Unique identifier of merchant in client

system (max .64 characters）

store_ext_id string Y Unique identifier of store in client system

(max .64 characters）

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

ShopeePay Payment APIs V1.65 123

 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

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

Field Type Description

ShopeePay Payment APIs V1.65 124

 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 object Store Entity

● 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 Point 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

ShopeePay Payment APIs V1.65 125

 ● 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

● 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 4 (follows merchant

withdrawal option) by default.

● 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

ShopeePay Payment APIs V1.65 126

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.

ShopeePay Payment APIs V1.65 127

ShopeePay Payment APIs V1.65 128
Appendix

Appendix 1A - Transaction Types

Transaction type Value Can be queried in Get Transactions API

Payment 13 Y

Refund 15 Y

Adjustment (Add) 32 Y

Adjustment (Deduct) 33 Y

Cash In 36 Y

Cash Out 37 Y

Payment Authorised 1000 N

Payment Captured 1001 N

Authorization Reversed 1002 N

Direct Payment* 1003 N

Capture Refund 1004 N

Direct Payment Refund* 1005 N

*[Note] The following Transaction Types have different values in Thailand and Vietnam
- Direct Payment: 13
- Direct Payment Refund: 15

ShopeePay Payment APIs V1.65 129

Appendix 1B - Payment Status

Transaction status Value

Payment successful 1

Payment not found 2

Payment refunded 3

Payment processing 5

Payment failed 6

ShopeePay Payment APIs V1.65 130

Appendix 1C - Transaction Status

Transaction status Value

Transaction initial 1

Transaction processing 2

Transaction successful 3

Transaction failed 4

Transaction expired 6

ShopeePay Payment APIs V1.65 131

Appendix 1D - Promotion Types

Promotion types Value

Coins 1

Cashback 2

Discount 3

ShopeePay Payment APIs V1.65 132

Appendix 2 - Point of Initiation

POI methods offered Binary value Decimal value to indicate

during onboarding

MPM Static only 00000001 1

MPM Dynamic only 00000010 2

CPM only 00000100 4

Deals only 00001000 8

Jump App only 00010000 16

Cash In only 00100000 32

Cash Out only 01000000 64

Account Linking Mode only 10000000 128

Cross Border only 100000000 256

Disbursement only 1000000000 512

Ticket Linking only 10000000000 1024

Sample decimal value calculations

POI methods offered Binary value Decimal value to indicate

during onboarding

MPM Static, MPM Dynamic 0011 3

MPM Static, CPM 0101 5

MPM Static, Cash In 00100001 33

ShopeePay Payment APIs V1.65 133

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 merchant
standards manual by Visa

ShopeePay Payment APIs V1.65 134

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

PH 1 Passport

PH 2 Driver’s License

PH 3 National Bureau of Investigation (NBI)

Clearance

PH 4 Alien Certificate of Registration

PH 5 Immigrant Certificate of Registration

PH 6 Unified Multi-Purpose ID (UMID)

PH 7 Social Security System (SSS) with Date

of Birth

PH 8 TIN ID

PH 9 Professional Regulation Commission

(PRC) ID

PH 10 PhilHealth ID with Date of Birth

PH 11 Postal ID (Issued 2015 onwards)

PH 12 Integrated Bar of the Philippines ID

PH 13 Philippine Postal ID (Issued November

2016 onwards)

PH 14 Police Clearance

ShopeePay Payment APIs V1.65 135

 PH 15 LTO Student Permit

PH 16 Senior Citizen ID

PH 17 Commission on Elections (COMELEC)

Voter’s ID

PH 18 TIN Card

PH 19 OFW ID Card

PH 20 PWD ID

PH 21 PhilSys ID

ShopeePay Payment APIs V1.65 136

Appendix 5 - Error Codes

Value Description

-2 A server dropped the connection

-1 A server error occurred

0 Success

1 Request parameters error, such as missing mandatory parameters, for

example, “Invalid token” or “Invalid currency” etc.

2 Permission denied

4 Merchant/store/user/transaction not found

5 Transaction processing, use Notify or Check Transaction Status API for

updated payment status

6 The user making the payment has not completed wallet activation

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

50 Payload sent is not a valid json

101 User wallet limit exceeded

102 User wallet limit exceeded

103 User exceeded daily payment limit

Limit will reset the next day

104 User wallet limit exceeded

105 Authorisation code is invalid

ShopeePay Payment APIs V1.65 137

 121 Client attempts to update completed transaction

126 User transaction limit reached

140 User wallet limit exceeded

150 Active linking count threshold reached

152 Fail to unlink due to ongoing auth

301 Invalid payment code or QR content

303 Merchant is trying to make payment to their own user account

304 Refund cannot be processed due to payment exceeding validity period

305 Merchant invalid

309 MDR fee don't have enough balance where merchant doesn't have enough
balance to refund a transaction

452 Unable to invalidate order as payment_ref_id cannot be found

601 Request to refund a payment transaction does not meet rules. This error is
also returned during refund block periods, set at 11.55pm to 3am by default.
This timing is subject to changing during campaign periods or system
maintenance.

602 Request to refund an unsuccessful payment transaction

604 Can not use this voucher

627 Invalid promo_ids

628 Selected point of initiation is disabled for merchant

629 Publisher Id not matched

630 SKU ID not matched

1001 User is not allowed to make the transaction

1002 This service is currently under maintenance

ShopeePay Payment APIs V1.65 138

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
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

ShopeePay Payment APIs V1.65 139

 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

V1.55 22.10.2020 S.F. 1 - Add promo_ids field in Create Dynamic QR API,

Create CPM Payment API and Create Order API
requests
2 - Add promo_id_applied field in Check Payment
Status, Get Transactions API responses, and
Notify Transaction Status callback

V1.55.1 13.11.2020 S.F. 1 - Remove promo_id_applied field from Notify

Transaction Status callback
2 - Add error code mapping for inv``alid promo_ids

V1.56 10.11.2020 Y.X. 1 - Add Account Linking flows and APIs

2 - Update Notify Transaction Status to generalise
the notification to all kinds of transactions
3 - Add Check Transaction Status API
4 - Add new Create Refund API
5 - Reorganise Set Merchant API response

V1.56.1 17.11.2020 G.K. 1- Added Cash In (Top Up) flows and APIs
2- Added New Transaction Type

ShopeePay Payment APIs V1.65 140

 3- Added New Point of Initiations

V1.56.2 08.1.2021 W.T, 1- Added new error code mapping - 5, for payment
Y.C processing, check callback and check status API
for updated status
2- Added new error code 1001 and 1002, to
handle access control and system maintenance
use case.

V1.56.3 14.1.2021 Y.X. 1- Updated Appendix 1A - Transaction Types table

2- Updated Account Linking APIs and sample
request/response.

V1.56.4 26.1.2021 S.F. 1- Updated default withdrawal option for Set Store
API

V1.56.5 26.2.2021 G.Z. 1 - Updated valid void period from 365 days to
within the create date of the original payment

V1.57 08.3.2021 G.S. 1 - Added Order Invalidate API

2 - Added new Error Code 452 for Order Invalidate
API

V1.58 13.4.2021 Y.X. 1 - Remove access scope field in Get User Info
API response
2 - Remove Appendix 6 - Access Scope
3 - Update `payment_reference_id`,
`auth_reference_id`, `reverse_auth_reference_id`
and `capture_reference_id` description in Account
Linking Direct Payment, Create Auth, Reverse
Auth, Capture APIs

V1.59 19.4.2021 G.Z. 1 - Deprecate Void API. Refund API provides the
same functionality to fulfil the refund needs of
ISVs and merchants

V1.60 26.4.2021 G.Z. 1 - Update supported currencies and API domains

for Thailand and Vietnam
2 - Indicate temporarily unavailable APIs in
Thailand and Vietnam: Create Auth, Reverse Auth,
Get User Info, Get Redeemable Coin Value, Create
Refund, Cash In (Topup) APIs

V1.61 19.5.2021 P.L. 1 - Indicate a temporarily unavailable field

(promo_ids) in Thailand and Vietnam for the

ShopeePay Payment APIs V1.65 141

 following APIs: Create Dynamic QR, Create CPM
Payment, Create Order, Direct Payment.
2 - Indicate a temporarily unavailable field
(use_coin) in Thailand and Vietnam for the
following APIs: Direct Payment.
3 - Update Thailand’s domain from .in.th to .co.th

V1.62 24.5.2021 G.Z., P.L. 1 - Add kyc_passed value in Get User Info API
2 - Indicate the partial refund capability of Create
Refund API [New] in Thailand and Vietnam
3 - Indicate a temporarily unavailable API in
Thailand and Vietnam: Get Transactions AP
4 - Add co_funding in the responses of following
APIs: Create Refund API [New], Check Transaction
Status API [New], Create CPM Payment and in the
request of Notify Transaction Status API.
Note: this field will only be available for Thailand
and Vietnam.

V1.63 19.7.2021 P.L. 1 - Add new error code 150 (active linking count
threshold reached) for Account Link API
2 - Indicate a temporarily unavailable field
(user_id_hash) in Thailand and Vietnam
3 - Add “platform_type” field in request
parameters for Create Order API in Thailand and
Vietnam and indicate that “point_of_initiation”
field’ in Create Order API is for ID, MY, PH, SG only
4 - Indicate non-applicable result codes in
Account Link API in Thailand and Vietnam
5 - Indicate a temporarily unavailable response
field (redirect_url_app) in Thailand and Vietnam
for Create Order API
6 - Add Transaction Type 1004 for Capture Refund
and 1005 for Direct Payment Refund
7 - Indicate a non-applicable flow: Cash in and
non-applicable APIs: Generate Cash In QR Code
API and Cash In QR Invalidate API in Thailand and
Vietnam
8 - Add expiry_time field in the following APIs:
Create Dynamic QR, Create CPM Payment, and
Create Order. This field is only applicable in
Thailand and Vietnam.
9 - Update Check Payment Status API to be Check

ShopeePay Payment APIs V1.65 142

 Transaction Status API, and Check Refund API to
be Check Refund API [New] in all payment
methods.

V1.64 23.7.2021 G.Z., P.L., 1 - Add eligible National ID Type value = 21, for PH
M.E. PhilSys ID
2 - Add error code 152 for failure to unlink account
linking due to ongoing auth transactions
3 - Add transaction_sn in the response
parameters for Direct Payment and Capture API
4 - Remove Check Payment Status and Create
Refund API from API docs as new merchants
shall always call Check Transaction Status and
Create Refund [New] API instead
5 - Add user_id_hash in the response of Get
Access Token API
6 - Add Ticket Linking in Payment method
Definition
7 - Add new Ticket Linking Flow
8 - Add new Point of Initiation for Cross Border,
Disbursement and Ticket Linking
9 - Indicate that the PIN verification process in
Direct Payment Flow is currently not applicable to
Thailand and Vietnam.
10 - Add response parameters for Notify
Transaction Status and retrying logic
11 - Indicate error 50 for wrong request format
12 - Indicate the availability of user_id_hash in all
API response for Thailand and Vietnam
13 - Add additional_info in the request parameters
of Direct Payment
14 - Add parameters appending mechanisms
when visiting return_url in App-to-app redirection
payment flow in Thailand and Vietnam
15 - Remove mcc and terminal_ ip request
parameters from CPM Create Payment API
16 - Remove point_of_initiation request
parameters from Create Order API

V1.65(WIP) 12.10.2021 P.L., G.Z., 1 - Remove the ‘Full Refund Only’ remark for
M.E. Indonesia, Malaysia, and Philippines. Partial
Refund is now available in all regions except for
Singapore.

ShopeePay Payment APIs V1.65 143

 2. Indicate max value 3600 (seconds)for
‘qr_validity_period’ request parameter in Create
Dynamic QR API and ‘validity_period’ request
parameter in Create Order API
3. Indicate the country code requirement for
‘phone’ request parameter in Account Link API
4. Indicate the Transaction Type for Direct
Payment as 13 and Direct Payment Refund as 15
in Thailand and Vietnam
5. Indicate that “promo_id_applied” field is not
available in Check Transaction Status response in
Thailand and Vietnam
6. Indicate that “promo_ids” request parameter is
applicable for usage in Thailand and Vietnam for
Create Dynamic QR API, Create CPM Payment API
and Create Order API
7. Add a new optional request parameter
linking_reference_id, and “qr” enumeration for
“platform_type” request parameter in Account
Link API for Thailand and Vietnam
8. Add “redirect_url_qr” response parameter in
Account Link API for Thailand and Vietnam
9. Add a new conditional request parameter
“linking_reference_id” in Get Access Token API,
and modify auth_code’s mandatory type to be
conditional for Thailand and Vietnam
10. Add new response parameters
“linking_reference_id”, “merchant_ext_id”,
“linking_status”, “create_time” and “update_time”
in Get Access Token API for Thailand and
Vietnam
11. Add a new conditional request parameter
“linking_reference_id” in Get User Info API, and
modify access_token’s mandatory type to be
conditional for Thailand and Vietnam
12. Add a new response parameter “linking_info”
in Get User Info API for Thailand and Vietnam
13. Indicated the max length as 20 characters for
“terminal_id” request parameter in Create
Dynamic QR API for Thailand and Vietnam

ShopeePay Payment APIs V1.65 144