Use SDK to sign a request and verify the signature

2024-05-29 10:14

Using the SDK provided by Antom for request signing and signature verification can significantly streamline your programming tasks and expedite the process of adding and validating API signatures. All available SDKs can be found in SDKs. If you prefer not to use the SDK, refer to the instructions of Sign a request and verify the signature.

To ensure the authenticity and integrity of data after transmission, Antom requires all requests to be signed and the signatures to be verified:

When calling an API, you must sign the request sent to Antom and verify the Antom response signature accordingly. For more information, see Call an API.
When receiving a notification, you must verify the Antom request signature. However, you do not need to sign the response for the notification. For more information, see Receive a notification.

Call an API

Prerequisite

Ensure that you have generated a pair of asymmetric public and private keys on the Antom Dashboard. For more information, see Generate keys.

Send Request & Handle Response

If you make an API call using SDK, the signing and verification process will be done automatically.

Add maven dependency:

You can find the latest version on GitHub.

copy
<dependency>
  <groupId>com.alipay.global.sdk</groupId>
  <artifactId>global-open-sdk-java</artifactId>
  <version>{latest_version}</version>
</dependency>

The following code sample shows how to use Java to send a request：

copy
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.alipay.global.api.AlipayClient;
import com.alipay.global.api.DefaultAlipayClient;
import com.alipay.global.api.exception.AlipayApiException;
import com.alipay.global.api.model.ams.*;
import com.alipay.global.api.model.constants.EndPointConstants;
import com.alipay.global.api.request.ams.pay.AlipayPayRequest;
import com.alipay.global.api.response.ams.pay.AlipayPayResponse;

@RestController
public class PaymentBySDK {

    /**
     * alipay public key, used to verify signature
     */
    private static final String SERVER_PUBLIC_KEY = "";

    /**
     * your private key, used to sign
     * please ensure the secure storage of your private key to prevent leakage
     */
    private static final String CLIENT_PRIVATE_KEY = "";

    /**
     * you clientId
     */
    private static final String CLIENT_ID = "";

    public static AlipayClient defaultAlipayClient = new DefaultAlipayClient(EndPointConstants.SG, CLIENT_PRIVATE_KEY, SERVER_PUBLIC_KEY);

    @RequestMapping("/pay")
    public Object pay() {
        AlipayPayRequest alipayPayRequest = composePayRequest();

        AlipayPayResponse alipayPayResponse = null;
        try {
            // automatically sign and verify
            alipayPayResponse = defaultAlipayClient.execute(alipayPayRequest);
        } catch (AlipayApiException e) {
            String errorMsg = e.getMessage();
            // handle error condition
        }
        return alipayPayResponse;
    }

    private AlipayPayRequest composePayRequest() {
        AlipayPayRequest alipayPayRequest = new AlipayPayRequest();

        alipayPayRequest.setClientId(CLIENT_ID);
        alipayPayRequest.setPath("/ams/api/v1/payments/pay");

        Env env = new Env();
        env.setTerminalType(TerminalType.WEB);
        alipayPayRequest.setEnv(env);

        Amount amount = new Amount();
        amount.setCurrency("CNY");
        amount.setValue("100");
        alipayPayRequest.setPaymentAmount(amount);

        Amount orderAmount = new Amount();
        orderAmount.setCurrency("CNY");
        orderAmount.setValue("100");

        Order order = new Order();
        order.setReferenceOrderId("ORDER_ID_1685599933871");
        order.setOrderDescription("Testing order");
        order.setOrderAmount(orderAmount);
        alipayPayRequest.setOrder(order);

        PaymentMethod paymentMethod = new PaymentMethod();
        paymentMethod.setPaymentMethodType("ALIPAY_CN");
        alipayPayRequest.setPaymentMethod(paymentMethod);

        alipayPayRequest.setPaymentRequestId("REQUEST_ID_1685599933871");

        alipayPayRequest.setProductCode(ProductCodeType.CASHIER_PAYMENT);

        alipayPayRequest.setPaymentRedirectUrl("https://www.example.com");
        return alipayPayRequest;
    }

}

Receive a notification

Handle a request

After receiving a notification from Antom, verify the signature of the request. The process of verifying the request signature is similar to the process introduced in the Send Request & Handle Response section. Follow these steps to verify the signature:

Obtain the Antom public key for the request from Prerequisite to verify the signature.
Get the request-time、client-id、signature from the request header.
Verify the signature.

The following code sample shows how to use Java to verify the signature:

copy
import javax.servlet.http.HttpServletRequest;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

import com.alipay.global.api.model.Result;
import com.alipay.global.api.model.ResultStatusType;
import com.alipay.global.api.response.AlipayResponse;
import com.alipay.global.api.tools.WebhookTool;

@RestController
public class PaymentNotifyHandleBySDK {

    /**
     * alipay public key, used to verify signature
     */
    private static final String SERVER_PUBLIC_KEY = "";
            
    /**
     * payment result notify processor
     * using <a href="https://spring.io">Spring Framework</a>
     *
     * @param request    HttpServletRequest
     * @param notifyBody notify body
     * @return
     */
    @PostMapping("/payNotify")
    public Object payNotifyHandler(HttpServletRequest request, @RequestBody String notifyBody) {

        // retrieve the required parameters from http request.
        String requestUri = request.getRequestURI();
        String requestMethod = request.getMethod();

        // retrieve the required parameters from request header.
        String requestTime = request.getHeader("request-time");
        String clientId = request.getHeader("client-id");
        String signature = request.getHeader("signature");

        Result result;
        AlipayResponse response = new AlipayResponse();

        try {
            // verify the signature of notification
            boolean verifyResult = WebhookTool.checkSignature(requestUri, requestMethod, clientId, requestTime, signature, notifyBody, SERVER_PUBLIC_KEY);
            if (!verifyResult) {
                throw new RuntimeException("Invalid notify signature");
            }

            // deserialize the notification body
            
            // update the order status with notify result

            // respond the server that the notification is received
            result = new Result("SUCCESS", "success", ResultStatusType.S);

        } catch (Exception e) {
            String errorMsg = e.getMessage();
            // handle error condition
            result = new Result("ERROR", errorMsg, ResultStatusType.F);
        }
        response.setResult(result);
        return ResponseEntity.ok().body(response);
    }

}