Get Started with ShopeePay

Get Started

An overview of the steps to start accepting payments using ShopeePay

Start by contacting ShopeePay 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 Online and In-Person Payment here to showcase the use of ShopeePay/SPayLater during 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 Signature Generation steps to create a signature that ShopeePay uses to verify its merchants.
Visit API Documentations to understand the structure of each API and follow the instructions to send request to the API.

Prerequisite

Merchant should fulfill 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

Each merchant will be assigned the following credentials for integration testing purposes.

Name	Description
Client ID	Client refers to the party that integrate with ShopeePay APIs. Each client is assigned a unique identifier known as the ClientID, and this Client ID must be included in the request header of every API call made to ShopeePay’s services.
Client Secret	Secret key for signature generation on transaction API. Client secret will be shared offline.
Public Key	ShopeePay’s public key which is used by the Client to verify API response/callback. Public key will be shared offline. ShopeePay Public Key will be provided in PKIX format

Merchant will also be required to prepare the following information.

Name	Description
Callback URL	URL to receive payment success notification from ShopeePay. Callback URL will be shared offline
Private Key	Client's private key which is used by the Client to sign API request. Generate private key in PKIX format: `openssl genrsa -out private key.pem 2048` Replace 2048 with your desired key length.
Public Key	Client's public key which is used by ShopeePay to verify API request. Public key needs to be shared by client offline. Public key should be using PKIX format. Generate public key in PKIX format: `openssl rsa -in privatekey.pem -pubout -out public_key.pem`

API Protocol Rules

This specifies the rules for calling APIs in this document.

Component	Format/Method
Transfer Mode	HTTPS
Submit Mode	POST/GET Method
Date Format	String - ISO 8601 (yyyy-MM-ddTHH:mm:ssZ , e.g. 2022-07-20T07:15:00+07:00)
Char Encoding	UTF-8
Signature	Asymmetric SHA-256withRSA, symmetric HMACSHA-512

Request and Response Parameter

Each API documentation includes a mandatory column for both request and response parameters. Here's what the column indicators mean:

M - Mandatory: These parameters must be included in every request.
O - Optional: These parameters can be omitted if not needed.
C - Conditional: These parameters are required only under specific circumstances.

API Parameter Specification

Access Token API

Access Token API Request Header

API header format of Access Token API will require these parameters.

Field	Type	Mandatory	Description
Content-Type	String	M	Media type of the resource, i.e. application/json
X-TIMESTAMP	String	M	Client’s current local time in yyyy-MM-ddTHH:mm:ss.TZD format
X-CLIENT-KEY	String	M	ClientID issued by ShopeePay
X-SIGNATURE	String	M	X-SIGNATURE: created using asymmetric signature SHA256withRSA algorithm (Private_Key, stringToSign) `stringToSign = X-CLIENT-KEY + “\|” + X-TIMESTAMP`

Access Token API Response Header

API header format of Access Token API will return these parameters.

Field	Type	Mandatory	Description
X-TIMESTAMP	String	M	Client’s current local time in yyyy-MM-ddTHH:mm:ss.TZD format
X-CLIENT-KEY	String	M	ClientID issued by ShopeePay

Transactional API

Transaction API Request Header

Each transaction request will require the following parameters in the header

Field	Type	Mandatory	Description
Content-Type	String	M	Media type of the resource, i.e. application/json
X-TIMESTAMP	String	M	Client’s current local time in yyyy-MM-ddTHH:mm:ss.TZD format
Authorization	String	C	Represents accessToken of a request, starts with keyword “Bearer” and followed by accessToken
X-SIGNATURE	String	M	Refer to Signature Generation and Signature Generation > Transaction Request API for details.
X-PARTNER-ID	String	M	Refers to Client ID issued by ShopeePay Unique identifier for caller
X-EXTERNAL-ID	String (36)	M	Numeric string. Reference number that should be unique in the same day under the same ClientID
ORIGIN	String	O	Origin domain e.g. www.domain.com
CHANNEL-ID	String (5)	M	PJP's channel id. Sample: App PC mweb Device identification on which the API services is currently being accessed by the end user (customer)

Signature Generation

A signature is required to authenticate the request. There are 2 types of signature that merchant needs to generate:

Signature for Access Token
Signature for Payment API Request

Access Token API

Signature for Access Token API is generated using the asymmetricSHA256withRSA cryptographic function and merchant’s private key

The following steps outline the process for generating signature for AccessToken Request:

Prepare the data to do signature, the data are:

EXAMPLE

Data	Description	Example
X-CLIENT-KEY	ClientID issued by ShopeePay	sample-client-id
X-TIMESTAMP	Client’s current local time in yyyy-MM-ddTHH:mm:ss.TZD format	`2022-08-11T11:13:43+08:00`

Generate the stringToSign (X-SIGNATURE) using:
EXAMPLE
```
<X-CLIENT-KEY> + ”|” + <X-TIMESTAMP>
```
Sample: sample-client-id|2022-08-11T11:13:43+08:00

Generate the signature by using merchant’s private key to encrypt the value using SHA256withRSA function. Sample codes in multiple programming languages are listed below step 4:

EXAMPLE

SYaKdVb4sB3Lq19TA7yDr/aH15xjteF2k1bbtWBAEOA/gIxKuSscCpZu5H5IKhPWnIweQtMBKgtUWdVncdOHOCVNRQ+SzUvHHQ7GHJTPtsedkbd3OnBHwCeh3tLPIQ5MOtHe/0WVcYwIPnZ8dj5Xa3afoUdfmFPEiK4Fb2nbc+5B9zaC+PkRtK6en1Hux4AqS9TUgdr7dR6Vat1vofe7hM7gzotjN0bHaCoH34S4WAJfPl79paZksAvl7I/E36ShgLGy2E/SOv9zChW/sOQxPLmJP8TgnM2cuKzDZBHD8Gn7ne5DGov13/N3++K/r0kU1i9kwTEZHzareSE+ObIOkQ==

Put the signature into Access Token HTTP header: "X-SIGNATURE"

EXAMPLE

X-SIGNATURE: 
SYaKdVb4sB3Lq19TA7yDr/aH15xjteF2k1bbtWBAEOA/gIxKuSscCpZu5H5IKhPWnIweQtMBKgtUWdVncdOHOCVNRQ+SzUvHHQ7GHJTPtsedkbd3OnBHwCeh3tLPIQ5MOtHe/0WVcYwIPnZ8dj5Xa3afoUdfmFPEiK4Fb2nbc+5B9zaC+PkRtK6en1Hux4AqS9TUgdr7dR6Vat1vofe7hM7gzotjN0bHaCoH34S4WAJfPl79paZksAvl7I/E36ShgLGy2E/SOv9zChW/sOQxPLmJP8TgnM2cuKzDZBHD8Gn7ne5DGov13/N3++K/r0kU1i9kwTEZHzareSE+ObIOkQ==

Java

JAVA EXAMPLE

openssl pkcs8 -topk8 -inform PEM -in yourpem.pem -outform DER -nocrypt -out yourprivate.der

JAVA EXAMPLE

import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.security.*;
import java.security.spec.PKCS8EncodedKeySpec;
import java.util.*;


private static String signSHA256RSA(String payload, String privateKeyFileName ) throws Exception {
   Path path = Paths.get(privateKeyFileName);
   byte[] privateKeyByteArray = Files.readAllBytes(path);
   PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(privateKeyByteArray);
   KeyFactory keyFactory = KeyFactory.getInstance("RSA");

   PrivateKey privateKey = keyFactory.generatePrivate(keySpec);
   Signature privateSignature = Signature.getInstance("SHA256withRSA");
   privateSignature.initSign(privateKey);
   privateSignature.update(payload.getBytes("UTF-8"));
   byte[] s = privateSignature.sign();
   return Base64.getEncoder().encodeToString(s);
}

Transactional API

Signature for Transactional API is generated using the symmetric HMACSHA-512 cryptographic function using an access token.

The following steps outline the process for generating signature for Payment API Request:

Prepare the data to do signature, the data are:

Data	Description	Example
HTTP Method	Method on each API for instance: GET, POST	POST
EndpointURL	EndpointURL is Relative path along with query parameters EndpointURL must be escaped. Please refer here for the escaped function	/v1.0/qr/qr-mpm-generate
AccessToken	An authorization issued to the client that used to access protected resources	AccessToken obtained by calling Access Token endpoint
HTTP Body	Raw body of the HTTP	{ "partnerReferenceNo": "F03B527114E9G0C7FG494", "amount": { "value": "17.00", "currency": "IDR" }, "feeAmount": { "value": "0.00", "currency": "IDR" }, "merchantId": "1209121278", "terminalId": "", "validityPeriod": "2022-07-22T10:45:58+08:00", "additionalInfo": { "externalStoreId": "2233", "convenienceFeeIndicator": "01", "promoIds": "" }}
X-TIMESTAMP	Client’s current local time in yyyy-MM-ddTHH:mm:ss.SSSTZD format	2022-08-02T19:16:20+08:00

Minify the request body

Before Minify:

JSON REQUEST

{
  "partnerReferenceNo": "F03B527114E9G0C7FG494",
  "amount": {
    "value": "17.00",
    "currency": "IDR"
  },
  "feeAmount": {
    "value": "0.00",
    "currency": "IDR"
  },
  "merchantId": "1209121278",
  "terminalId": "",
  "validityPeriod": "2022-07-22T10:45:58+08:00",
  "additionalInfo": {
    "externalStoreId": "2233",
    "convenienceFeeIndicator": "01",
    "promoIds": ""
  }
}

After Minify:

JSON REQUEST

{"partnerReferenceNo":"F03B527114E9G0C7FG494","amount":{"value":"17.00","currency":"IDR"},"feeAmount":{"value":"0.00","currency":"IDR"},"merchantId":"1209121278","terminalId":"","validityPeriod":"2022-07-22T10:45:58+08:00","additionalInfo":{"externalStoreId":"2233","convenienceFeeIndicator":"01","promoIds":""}}

Generate body hash: Lowercase(HexEncode(SHA-256(RequestBody))). The hex encoded SHA-256 hash of the request body should look like this:
EXAMPLE
```
3fb04055423bc3a488c923b134d1c9ca9de68132aef7535d3b97f614a165df8c
```

Generate the final payload by composing the stringToSig

EXAMPLE

HTTP METHOD + ":" + EndpointURL + ":" + AccessToken + ":" Lowercase(HexEncode(SHA-256(RequestBody))) ":" + <X-TIMESTAMP>

This is how the stringToSign look like:

EXAMPLE

POST:/v1.0/qr/qr-mpm-generate:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJDbGllbnRJRCI6Ik1IMjAyMjA3MDhCIiwiZXhwIjoxNjU4NzIwOTk5NjY5LCJpYXQiOjE2NTg3MTczOTk2NjksImlzcyI6Ik1IMjAyMjA3MDhCIiwibmJmIjoxNjU4NzE3Mzk5NjY5fQ.hv0dubKQTeTR4n2VK\_qzf8N3MPUv1wEc8LiMa1eglVc:3fb04055423bc3a488c923b134d1c9ca9de68132aef7535d3b97f614a165df8c:2022-08-02T19:16:20+08:00</u>](http://post/v1.0/qr/qr-mpm-generate:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJDbGllbnRJRCI6Ik1IMjAyMjA3MDhCIiwiZXhwIjoxNjU4NzIwOTk5NjY5LCJpYXQiOjE2NTg3MTczOTk2NjksImlzcyI6Ik1IMjAyMjA3MDhCIiwibmJmIjoxNjU4NzE3Mzk5NjY5fQ.hv0dubKQTeTR4n2VK_qzf8N3MPUv1wEc8LiMa1eglVc:3fb04055423bc3a488c923b134d1c9ca9de68132aef7535d3b97f614a165df8c:2022-08-02T19:16:20+08:00

Generate signature using the final payload. The symmetric HMAC_SHA512 (clientSecret, stringToSign) should look like this. Sample codes in multiple programming languages are listed below step 6:
EXAMPLE
```
3ZcDuB8ZBJBqN+jWdoH1nmGg+z+n1hkE6JOGQ3ziWTgX+vU4+CdypOFwBNbT1SZ7zRryIFqQr5/eLHIFGO//EA==
```

Put the signature into Transactional API Request HTTP header: "X-SIGNATURE"

EXAMPLE

X-SIGNATURE: 3ZcDuB8ZBJBqN+jWdoH1nmGg+z+n1hkE6JOGQ3ziWTgX+vU4+CdypOFwBNbT1SZ7zRryIFqQr5/eLHIFGO//EA==

Note:

EndpointURL consists of a relative path including the Request Parameters. For example: /1.0/get-auth-code/test?uid=1234&order_id=1234
EndpointURL must be escaped. For example, an unescaped url looks like this/1.0/get-auth-code/test?uid=1234&order_id=1234. You need to escape the whole Request Parameters to /1.0/get-auth-code/test?uid%3D1234%26order_id%3D1234. You can refer here for the escape function. We suggest you to unescape first before escaping the EndpointURL. Below is a javascript example
EXAMPLE
```
escapedParameters = encodeURIComponent(unescape(pm.request.url.query))
```
If does not have minify(Request Body), then can use empty string.

Java

JAVA EXAMPLE

<dependency>
   <groupId>org.json</groupId>
   <artifactId>json</artifactId>
   <version>20210307</version> <!-- Use the latest version -->
</dependency>

JAVA EXAMPLE

package org.example;

import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.security.InvalidKeyException;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.json.JSONObject;
import org.json.JSONException;

public class Main {

   public static String hmacSha512(byte[] body, String token, String timestamp, String method, String url, String clientSecret) throws Exception {
       // 1. Minify the request body
       byte[] miniBody = minify(body);

       // 2. Generate body hash
       String bodyHash = bodySha256WithHexEncode(miniBody);

       // 3. Generate final payload
       String payload = genPayload(method, url, token, bodyHash, timestamp);

       // 4. Use payload to generate signature
       String finalSign = generateHmacSha512(payload, clientSecret);
       return finalSign;
   }

   private static byte[] minify(byte[] body) throws Exception {
       if (body.length == 0) {
           throw new Exception("Body is empty");
       }
       try {
           String jsonString = new String(body, "UTF-8");
           JSONObject json = new JSONObject(jsonString);
           String minifiedJson = json.toString();
           return minifiedJson.getBytes("UTF-8");
       } catch (JSONException e) {
           throw new Exception("Failure encountered compacting JSON: " + e.getMessage(), e);
       }
   }

   private static String bodySha256WithHexEncode(byte[] body) throws NoSuchAlgorithmException {
       MessageDigest digest = MessageDigest.getInstance("SHA-256");
       byte[] hash = digest.digest(body);
       StringBuilder hexString = new StringBuilder();
       for (byte b : hash) {
           String hex = Integer.toHexString(0xff & b);
           if (hex.length() == 1) {
               hexString.append('0');
           }
           hexString.append(hex);
       }
       return hexString.toString().toLowerCase();
   }

   private static String genPayload(String method, String url, String token, String bodyHash, String timestamp) {
       return String.format("%s:%s:%s:%s:%s", method, url, token, bodyHash, timestamp);
   }

   private static String generateHmacSha512(String payload, String clientSecret) throws NoSuchAlgorithmException, InvalidKeyException {
       Mac mac = Mac.getInstance("HmacSHA512");
       SecretKeySpec secretKeySpec = new SecretKeySpec(clientSecret.getBytes(), "HmacSHA512");
       mac.init(secretKeySpec);
       byte[] hmacSha512 = mac.doFinal(payload.getBytes());
       return Base64.getEncoder().encodeToString(hmacSha512);
   }
}

Callback Signature Validation

Upon receiving the API callback, Client should verify the signature of the callback in the following ways.

Take the signature from HTTP header "X-SIGNATURE" in the callback request from ShopeePay

Example signature:

EXAMPLE

hnha4pl/3qPxBlAoRLvxzQzCt3wWqBHDTQfRkvI9o7ZDkwsM9NI0YxZVkb/TyDu7wrkv7EVubMihyt4Kn1cjpXoU9MRQ2MHFAsN9tm3R7Qj0kQwvmhCsjOSp9zPhBfT99Syg4TdjHpLPMnxPHEmarZKHPzCdcJCtdz1ohZ6ilamyjLazICXpsezf4V3bZSiXMTS1CB7r3Nc0FFq6x2dMTCV0FU0/rJT7TVtntpgHee2xtcJIPpAqb+zyEAeyBaC5oGtTqlgd5D/bmAbi+t8wPdMTWC0xVpzoHdALOPoStwaxooMiGBsuGYz5xEgCFYGPOYN5dkPS/QJHvd+DhxhbGA==

Generate stringToSign based on this following format:
Format:
EXAMPLE
```
HTTPMethod + ":" + callbackURL + ":" + Hex(SHA256(requestBody)) + ":" + timestamp
```
Note:
- The SHA256 sum needs to be formatted using hexadecimal integer.
- The value of timestamp is taken from the HTTP header "X-TIMESTAMP" in the callback request.
- ShopeePay uses full path including the domain for merhant’s callbackURL
Example:
EXAMPLE
```
POST:https://example.callback.com/Shopee/v1.0/debit/notify:2ae8474e00b1a65fc67cba1b4f6446b94bb50a0fc9f575ae10d545a2ddc98068:2024-03-04T08:44:30+07:00
```
Verify the correctness of the signature based on Asymmetric SHA-256withRSA encryption using ShopeePay public key.

Sample Codes to verify the signature:

Java

JAVA EXAMPLE

package seamless;

import java.nio.charset.StandardCharsets;
import java.security.KeyFactory;
import java.security.MessageDigest;
import java.security.PublicKey;
import java.security.Signature;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;
import java.util.Formatter;

public class SignatureVerifier {

  private static final String SHOPEE_PUBLIC_KEY = "-----BEGIN PUBLIC KEY-----\n" +
    "..." +
    "-----END PUBLIC KEY-----";

  public static void main(String[] args) {
    try {
      String sign = "your_signature_to_be_verified";
      String callbackURL = "https://example.com/Shopee/v1.0/debit/notify";
      String reqPayload = "{\"example_field\":\"example_value\"}";
      String timestamp = "2024-03-04T08:44:30+07:00";
      System.out.println(verifySignature(callbackURL, reqPayload, timestamp, sign));
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
/**
   * @param callbackURL callback URL of merchant
   * @param reqPayload the HTTP request payload
   * @param timestamp the value of HTTP request header X-TIMESTAMP
   * @param signToVerify the value of HTTP request header X-SIGNATURE
   * */
  public static boolean verifySignature(String callbackURL, String reqPayload, String timestamp, String signToVerify) throws Exception {
    // Compute string to sign
    String stringToSign = String.join(":",
      "POST",
      callbackURL,
      sha256Hex(reqPayload),
      timestamp
    );
    System.out.println("String to sign:" + stringToSign);

    // Load ShopeePay public key
    String pubKeyPEM = SHOPEE_PUBLIC_KEY
      .replace("-----BEGIN PUBLIC KEY-----", "")
      .replaceAll(System.lineSeparator(), "")
      .replace("-----END PUBLIC KEY-----", "");
    byte[] publicKeyBytes = Base64.getDecoder().decode(pubKeyPEM);
    X509EncodedKeySpec keySpec = new X509EncodedKeySpec(publicKeyBytes);
    PublicKey pubKey = KeyFactory.getInstance("RSA").generatePublic(keySpec);

    // initialise and prepare Signature instance
    Signature signature = Signature.getInstance("SHA256withRSA");
    signature.initVerify(pubKey);
    signature.update(stringToSign.getBytes(StandardCharsets.UTF_8));

    // Base64 decode the signature
    byte[] signatureBytes = Base64.getDecoder().decode(signToVerify);

    // verify the signature
    return signature.verify(signatureBytes);
  }

  private static String sha256Hex(String data) throws Exception {
    byte[] hash = sha256(data.getBytes(StandardCharsets.UTF_8));
    try (Formatter formatter = new Formatter()) {
      for (byte b: hash) {
        formatter.format("%02x", b);
      }
      return formatter.toString();
    }
  }

  private static byte[] sha256(byte[] data) throws Exception {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    return digest.digest(data);
  }
}

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.
Empty parameters may be returned in the following format by default, unless stated otherwise.

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

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.

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

Append the region code to the end of the domain.

Environment	Domain
sandbox	api.snap.uat.airpay.co.id
live	api.snap.airpay.co.id

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.

IMPORTANT:

ShopeePay may introduce new parameters in future updates. Merchants should avoid enforcing strict validation on the response body and callback parameters to ensure seamless compatibility.