Getting Started

Introduction

This document provides an overview of Easyway API, including it's authentication mode, request/response format, and detailed access endpoints.

APP Access Process

Get App ID and App Secret

Please contact Easyway Dev Team to get your unique app_id and app_secret for making calls to the API.

Public Key

Public key is used to verify the API requests. Please contact Easyway Dev Team to provide your public key information.

IP WhiteList

Please contact Easyway Dev Team to provide the IP address for whitelist. To help your integration operate securely, we must verify that it’s communicating through one of our listed IP addresses.

If your integration also receives webhooks from us, make sure these events originate from a whitelisted IP address.

API Call Description

Endpoints

Dev: https://dev-api.easyway.com
Production: https://api.easyway.com

Http Method

GET/POST

Common Header

HEADER PARAMETERS

Header Name	Description	Is Required
X-Request-Id	Unique request id	Yes
Authorization	JWT access token, all POST required	Conditional
Sign	RSA Signature, all POST required	Conditional
X-Timestamp	Timestamp, used for signature verification, required for POST requests.	Conditional
Content-Type	for POST request, needs to be application/json	Conditional
X-Unit-Id	All sub-merchant requests are required	Conditional

Sign

Signature is the verification of the body of the messages during the interaction between the Easyway and the merchant. Signature occurs in post http request. There is also a webhook message used by Easyway to notify merchants of data changes.

Easyway uses the RSA private key to decrypt, and the RSA public key to sign. Therefore, during the API interaction, there are merchant RSA public and private keys and Easyway RSA public and private keys.

The signing rules are as follows:

• The merchant sends a request to Easyway, the merchant uses its own RSA private key to sign, and Easyway uses the merchant's RSA public key to verify the signature;
• Easyway sends a notification to the merchant, Easyway uses its own RSA private key to sign, and the merchant uses the Easyway RSA public key to verify the signature;
• Signing is to encrypt the http request body, app_id, timestamp, For specific rules, see the following signature example;
• Whether it is the public and private keys of the merchant or the platform, the generation method is to use the PKCS8 padding method and 2048 length Tool;
• Sign out and base64 as the signed string;
• Put the encrypted string in the header Sign.

Sample code

Code
 
package com.pyvio.developer.sdk.aop;

import org.apache.commons.codec.binary.Base64;

import java.security.KeyFactory;
import java.security.PrivateKey;
import java.security.PublicKey;
import java.security.Signature;
import java.security.spec.PKCS8EncodedKeySpec;
import java.security.spec.X509EncodedKeySpec;

public class SignTest {

    /**
     * 参数签名(${appId}${timestamp}${requestBody})
     * @param content
     * @param privateKey
     * @return
     * @throws Exception
     */
    public static String sign(String content,String privateKey) throws Exception {
        Signature signature = Signature.getInstance("SHA256WithRSA");
        PrivateKey prk = getPrivateKeyFromPKCS8("RSA",privateKey);
        signature.initSign(prk);
        byte[] bytes = content.getBytes("UTF-8");
        signature.update(bytes);
        byte[] signed = signature.sign();
        return Base64.encodeBase64String(signed);
    }

    public static boolean signCheck(String content,String sign, String publicKey) {
        try {
            PublicKey pubKey = getPublicKeyFromX509("RSA", publicKey);
            java.security.Signature signature = java.security.Signature.getInstance("SHA256WithRSA");
            signature.initVerify(pubKey);
            signature.update(content.getBytes("UTF-8"));
            return signature.verify(Base64.decodeBase64(sign.getBytes()));
        } catch (Exception e) {
            return false;
        }
    }

    private static PrivateKey getPrivateKeyFromPKCS8(String algorithm, String privateKey) throws Exception {
        KeyFactory keyFactory = KeyFactory.getInstance(algorithm);
        byte[] encodedKey = privateKey.getBytes();
        encodedKey = Base64.decodeBase64(encodedKey);
        return keyFactory.generatePrivate(new PKCS8EncodedKeySpec(encodedKey));
    }

    private static PublicKey getPublicKeyFromX509(String algorithm, String publicKey) throws Exception {
        KeyFactory keyFactory = KeyFactory.getInstance(algorithm);
        byte[] encodedKey = publicKey.getBytes();
        encodedKey = Base64.decodeBase64(encodedKey);
        return keyFactory.generatePublic(new X509EncodedKeySpec(encodedKey));
    }

    public static void main(String[] args) throws Exception {
        //partner app id
        String appId = "1569641270953589504";
        //request time
        Long timestamp = 1666332361000L;
        //partner rsa private key
        String privateKey = "MIICdQIBADANBgkqhkiG9w0BAQEFAASCAl8wggJbAgEAAoGBALxGyg3/boLT2I8dQnC3Njc2XIDJgZM/G4wqsDDUVoy/PQ2THA39sKHiLsTg71zVbQZ4+UYWm1aTlms7KuBuOmvmdIzKuI04NbSuDeAbAtnraizhELSOpVQFNom2tIGHw4/46VuF3bE0rgFjKGqrRI9xOVEcDGZlP4h9JatQEgytAgMBAAECgYADZ1dX9Awy+A+NlAFm4BQrcXFy1xt7GIGUHaSUCe3N7sxY45uB+F+vyVh6aJm74QlCaJvmQv62Lg5t1HOQ2pcHD6/r7G0lykjYJ3JEAmF3KKm/FgPqX9MGqZCBNHp3oQaHMf8WwRfjxr/EBT1QfdItCGjiENJ4bjSJo9qzEPtjSQJBAMx/r6clsTUdpeskw60UMJG17Af5Fc/SNCsq8hdmCqva0QtT1l/vprmwEH1hKXlA9au9cIESp0ceABH86jE9Vu8CQQDrsTt/S6iiWAiJKA8eYWSEcPyQXoB+tveg4ZoKUwG+fT5t9tXOuPZGmC7CWsAATfO88/ySGqNyIlFgSDvTM3YjAkB+c9JdLCyI6L1pSwGIq/xgjbrXL0oyiQvjSZoLp/ifTh6Hv57HEfzpw5pevU8VAHspaGoCFlPD4SQv+1GhgwmXAkAd6grBJ1sp7751mg4BLx9Q5/5GXJg2fQaE9t1UPiDUipTn5BJTAIrRfvNAW8BOyZYL/3OpH5RrIgvuCnz9W2S9AkB19MQtKSc3Ba36Jo3C0kvTdeSDBR4o+ah+bzhwg/Hj8EKYp4IoyW8mx32WXtSLGp8OjupPlZ65PUkzy838Eo8v";
        //partner rsa public key
        String publicKey = "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC8RsoN/26C09iPHUJwtzY3NlyAyYGTPxuMKrAw1FaMvz0NkxwN/bCh4i7E4O9c1W0GePlGFptWk5ZrOyrgbjpr5nSMyriNODW0rg3gGwLZ62os4RC0jqVUBTaJtrSBh8OP+Olbhd2xNK4BYyhqq0SPcTlRHAxmZT+IfSWrUBIMrQIDAQAB";
        // post request json body,read from request stream
        String requestBody = "{\"grant_type\":\"client_credentials\",\"app_id\":\"1569641270953589505\",\"app_secret\":\"bc2ead7739f447c49032b4aef7818c47\"}";

        //generate rule
        String signContent = appId + timestamp + requestBody;
        String sign = sign(signContent,privateKey);
        System.out.println(sign);
        System.out.println(signCheck(signContent,sign,publicKey));
    }
}

Errors

If a request fails, we will respond with error details. If the response is not received, it may mean that the network has timed out, and please try again.

Response Code	Description
B_XXX	Bad request - The request is invalid due to missing parameters, an incorrect structure, or failure in another validation test.
S_XXX	Business process failure

Error Codes

Response Code	Description
S_Common_SystemError	System error, please contact Easyway dev team
B_Common_AuthError	Unauthorized - Please ensure that a valid authentication token is provided.
B_Auth_TokenInvalidError	Unauthorized - Please get a new authentication token.
B_Common_NotFound	Not found - The requested endpoint does not exist.
B_Common_ParamError	An incorrect type or failed validation test occurred with a provided argument.

Failed Example Response

Code
 
{
  "code": "B_Common_ParamError",
  "message": "Invalid parameter: app_id is required"
}

Success Example Response

Code
 
{
  "code": "SUCCESS",
  "message": null,
  "data": {}
}