Get Started with ShopeePay

Get Started

An overview of the steps to start accepting payments using ShopeePay

Start by contacting ShopeePay’s integration team to sign the NDA (Non-Disclosure Agreement) and commercial agreement.
Choose your integration to match your business needs:
- In-Person Payments
- Online Payments
- Please refer to the ShopeePay/SPayLater Branding Guideline for In-Person Payment and Online Payment here to showcase the use of ShopeePay/SPayLater in the payment flow
You will be assigned onboarding credentials to start integration testing purposes.
Develop according to the stated API rules to interact with ShopeePay Payment APIs.
Follow the steps provided in the Signature Generation to perform the signature verification.
Visit API Documentations to understand the structure of each API and follow the instructions to send request to the API.

Prerequisite

Merchant should fulfil the following requirements to interact with ShopeePay APIs:

To be compatible with OAuth 2.0 protocol and HMAC used by ShopeePay to authorize calls.
Merchants should use TLSv1.2 or TLSv1.3 for TLS handshake.
Merchants should integrate directly with ShopeePay endpoints without the use of a SDK.

Onboarding

Once the commercial agreement between merchant and ShopeePay is finalized, each merchant will be assigned the following credentials for integration testing purposes.

Credentials	Description
Client ID	Client refers to the party that integrate with ShopeePay APIs. Each client is assigned a unique identifier known as the Client ID, and this Client ID must be included in the request header of every API call made to ShopeePay's services.
Secret Key	A secret key that is shared between ShopeePay Server and Merchant. This key is used to generate the Signature to authenticate the Merchant. When handling sensitive information such as merchant ID and secret key, please do not hard code the secret key in a frontend application. All API calls should only be made from the Merchant’s servers.

Access Nodes

ShopeePay access nodes are country specific, each country will have their own API domains to be called.

Region	Abbreviation	Region 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
Staging	api.uat.wallet.airpay.<region code>
Production	api.wallet.airpay.<region code>

API Protocol Rules

This specifies the rules for calling ShopeePay APIs.

Component	Format/Method
Transfer Mode	HTTPS
Submit Mode	POST Method
Date Format	UNIX (seconds)
Char Encoding	UTF-8
Signature	HMAC, SHA-256, Base64

API Parameters Specifications

Request Header

All requests will require the following parameters in the header:

Name	Description
Client ID	Client refers to the party that integrate with ShopeePay APIs. Each client is assigned a unique identifier known as the Client ID, and this Client ID must be included in the request header of every API call made to ShopeePay's services.
Signature	Generated using the shared secret that is given by Shopee to authenticate the API caller.

Response Body

The ShopeePay API response body is in JSON format.

Considerations to take note of in the response body:

Parameters can be returned in a random sequence.
Empty parameters may be returned in the following format by default, unless stated otherwise.
Additional parameters may be returned in future without advance notice from ShopeePay.
Merchant system’s logic must not assume that the order of arrangement of response parameters or the total number of parameters returned will remain constant throughout time.

Type	Empty Response
Integer	0
String	Empty string, or "0" if the field represents a numerical value (e.g. amount, timestamp)
Object	Null
Array	Empty array
Boolean	False

URL Query Parameters

The URL query parameters can be returned in a random sequence.
Additional query parameters may be added in the future without advance notice from ShopeePay.
Query parameters are case-sensitive.

Security Specifications

Generate HMAC Signatures

Signature generation is essential for authenticating API requests between ShopeePay and the merchant. The signature is generated using a confidential shared secret key and algorithm, provided by ShopeePay. Merchants may use the common signature modes such as hash-based message authentication code (HMAC), SHA-256, and Base64.

GO EXAMPLE

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

Copy

JS EXAMPLE

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

Copy

Steps to Generate HMAC Signatures

If the request has a body, the request body must be hashed using the SHA-256 algorithm and represented as a base-64 encoded value. To generate a signature, the HTTP request body is hashed using HMAC with the SHA-256 algorithm and the shared secret key, operated on the request JSON to ensure authenticity of the request.

Secret: pz148x0gXyPCLHxnlhEydNLg55jni91i

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

Copy

Hash the JSON content by using the SHA256 algorithm.

5f5532bf23018674788770f43743522dff1af5782243fab06b1e8677a7391d4c

Copy

Encode to Base64

X1UyvyMBhnR4h3D0N0NSLf8a9XgiQ/qwax6Gd6c5HUw=

Copy

Signature Validate

Upon receiving the API response, the Merchant should validate the signature of the response:

Use the shared secret to sign the response body to obtain the response signature.
Compare the generated signature to the signature in the header of the API response.
Signatures from steps #1 and #2 must be identical. If they are different, the response should not be trusted.

To assist with signature validation, you can use online tools such as base64encode.org. These tools provide a convenient way to decode and verify signatures during the API integration process.

Request Header

Include the signature in the request

The signature should be added in the HTTP header in the following format:

SH EXAMPLE

X-Airpay-MerchantId: <merchantid>
X-Airpay-Req-H: <request_signature>

Copy

Backward Compatible Changes

Backward compatible or non-breaking changes refer to API changes that allow the integration to continue using the API without any additional changes required at Merchant’s side. ShopeePay may make such changes on their sole discretion without informing the existing Merchants in advance, as such changes are deemed to not break any integration implemented by the Merchant.

ShopeePay considers the following changes as non-breaking:

Add new API resource or new types of server callback to a new endpoint.
Add new or remove optional field to existing API request parameters.
Add new fields to existing API response/server callback parameters.
Increase or decrease the max length limit of existing fields on existing API response / server callback parameters.
Change the order of fields in existing API responses or server callback parameters.
Increase the max length limit of request fields on existing API request parameters.

Get Started with ShopeePay

Get Started

Prerequisite

Onboarding

Access Nodes

API Protocol Rules

API Parameters Specifications

Request Header

Response Body

URL Query Parameters

Security Specifications

Generate HMAC Signatures

GO EXAMPLE

JS EXAMPLE

Steps to Generate HMAC Signatures

Signature Validate

Request Header

SH EXAMPLE

Backward Compatible Changes

On this page