Call an API via adding a signature

2024-03-08 07:12

Before calling an API, signing a request is needed. After sending the request and obtaining the response, you need to validate the response signature accordingly.

Sign a request

Procedures

Obtain your private key, represented by privateKey, which is used to sign a request.
Construct the content to be signed (Content_To_Be_Signed).
Calculate and generate the signature.
Add the generated signature to the request header.

For details of each step, see the following examples.

Example

1. Obtain your private key to sign the request

Get your private key ready, which must be a 2048-bit RSA key and is used to generate the signature later.

2. Construct the content to be signed

For example, a request has the following properties:

HTTP_URI : for example, /api/v2/payments/pay
Client-Id : TEST_5X00000000000000
Request-Time : 2019-05-28T12:12:12+08:00
HTTP_BODY : the body looks like the following format.

copy
{
 "order":{
    "orderId":"OrderID_0101010101",
    "orderDescription":"sample_order",
    "orderAmount":{
       "value":"100",
       "currency":"JPY"
    }，
 },
 "paymentAmount":{
    "value":"100",
    "currency":"JPY"
 },
 "paymentFactor": {
     "isInStorePayment": "true"
 } 
}

By complying with the Syntax of Content_To_Be_Signed, the content to be signed (Content_To_Be_Signed) is created as follows:

copy
POST /api/v2/payments/pay
TEST_5X00000000000000.2019-05-28T12:12:12+08:00.{
"order":{
    "orderId":"OrderID_0101010101",
    "orderDescription":"sample_order",
    "orderAmount":{
       "value":"100",
       "currency":"JPY"
    }，
 },
 "paymentAmount":{
    "value":"100",
    "currency":"JPY"
 },
 "paymentFactor": {
     "isInStorePayment": "true"
 } 
}

Syntax of `Content_To_Be_Signed`

copy
<HTTP_METHOD> <HTTP_URI>
<Client-Id>.<Request-Time>.<HTTP_BODY>

HTTP_METHOD : POST
HTTP_URI : For example, if the HTTP URL is https://example.com/api/v2/payments/pay, this property is /api/v2/payments/pay.
Client-Id : is used to identify a client, and is associated with the keys that are used for signature and. You can get this field from the request header.
Request-Time: Specifies the time when a request is sent, as defined by ISO8601. Note: This field must be accurate to milliseconds. For example, 2019-05-28T12:12:12+08:00 . You can get this field from the request header.
HTTP_BODY : the data body of a request.

3. Calculate and generate the signature

Use the sha256withrsa method that involves the proper algorithm and private key to calculate and generate the signature.

copy
generatedSignature=base64UrlEncode(sha256withrsa(<Content_To_Be_Signed>), <privateKey>)

Content_To_Be_Signed: the content to be signed that is obtained in step 2.
privateKey : the private key value that is obtained in step 1.
sha256withrsa : the algorithm to use, RSA with SHA256.

For example, the generated signature generatedSignature looks as follows:

copy
KrwDE9tAPJYBb4cUZU6ALJxGIZgwDXn5UkFPMip09n%2FkYKPhEIII%2Fki2rYY2lPtuKVgMNz%2BtuCU%
2FjzRpohDbrOd8zYriiukpGAxBQDIVbatGI7WYOcc9YVQwdCR6ROuRQvr%2FD1AfdhHd6waAASu5Xugow9
w1OW7Ti93LTd0tcyEWQYd2S7c3A73sHOJNYl8DC1PjasiBozZ%2FADgb7ONsqHo%2B8fKHsLygX9cuMkQY
TGIRBQsvfgICnJhh%2BzXV8AQoecJBTrv6p%xxxx

4. Add the generated signature to the request header

a. Assemble a signature string as the following syntax.

copy
'Signature: algorithm=<algorithm>, keyVersion=<key-version>, signature=<generatedSignature>'

algorithm , keyVersion : see the header of the Message structure chapter.
generatedSignature : the signature that is generated in step 3.

For example:

copy
'Signature: algorithm=RSA256, keyVersion=1, signature=KrwDE9tAPJYBb4cUZU6ALJxGIZgwDXn5UkFPMip09n%2FkYKPhEIII%2Fki2rYY2lPtuKVgMNz%2BtuCU%2FjzRpohDbrOd8zYriiukpGAxBQDIVbatGI7WYOcc9YVQwdCR6ROuRQvr%2FD1AfdhHd6waAASu5Xugow9w1OW7Ti93LTd0tcyEWQYd2S7c3A73sHOJNYl8DC1PjasiBozZ%2FADgb7ONsqHo%2B8fKHsLygX9cuMkQYTGIRBQsvfgICnJhh%2BzXV8AQoecJBTrv6p%xxxx'

b. Add the signature string to the request header.

For example：

copy
-H 'Signature: algorithm=RSA256, keyVersion=1, signature=KrwDE9tAPJYBb4cUZU6ALJxGIZgwDXn5UkFPMip09n%2FkYKPhEIII%2Fki2rYY2lPtuKVgMNz%2BtuCU%2FjzRpohDbrOd8zYriiukpGAxBQDIVbatGI7WYOcc9YVQwdCR6ROuRQvr%2FD1AfdhHd6waAASu5Xugow9w1OW7Ti93LTd0tcyEWQYd2S7c3A73sHOJNYl8DC1PjasiBozZ%2FADgb7ONsqHo%2B8fKHsLygX9cuMkQYTGIRBQsvfgICnJhh%2BzXV8AQoecJBTrv6p%xxxx'

Send a request

Construct a request by adding the Client-Id, Request-Time, and Signature fields to the request header. After a request is constructed, you can use common tools, like cURL or Postman to send the request. In the following example, cURL is used.

copy
curl -X POST \
  https://example.com/api/v2/payments/pay \
  -H 'Content-Type: application/json' \
  -H 'Client-Id: TEST_5X00000000000000' \
  -H 'Request-Time: 2019-05-28T12:12:12+08:00' \
  -H 'Signature: algorithm=RSA256, keyVersion=0, signature=KrwDE9tAPJYBb4cUZU6ALJxGIZgwDXn5UkFPMip09n%2FkYKPhEIII%2Fki2rYY2lPtuKVgMNz%2BtuCU%2FjzRpohDbrOd8zYriiukpGAxBQDIVbatGI7WYOcc9YVQwdCR6ROuRQvr%2FD1AfdhHd6waAASu5Xugow9w1OW7Ti93LTd0tcyEWQYd2S7c3A73sHOJNYl8DC1PjasiBozZ%2FADgb7ONsqHo%2B8fKHsLygX9cuMkQYTGIRBQsvfgICnJhh%2BzXV8AQoecJBTrv6p%xxxx' \
  -d '{
      "order":{
          "orderId":"OrderID_0101010101",
          "orderDescription":"sample_order",
          "orderAmount":{
             "value":"100",
             "currency":"JPY"
          }
       },
       "paymentAmount":{
          "value":"100",
          "currency":"JPY"
       },
       "paymentFactor": {
           "isInStorePayment": "true"
       } 
}'

Handle a response

After you receive a response, you need to validate the signature of the response. A response consists of response headers and the response body. For example:

The response header sample

copy
Client-Id: 5X00000000000000
Response-Time: 2019-05-28T12:12:14+08:00
Signature: algorithm=RSA256, keyVersion=0, signature=p9T2hXxIjek0UOLw3fwlthNsV6ATaioIvu8X1uFx8a9tE87d2XEhqylnf0KjifJ3WhCoMokl
GwwlDS3tsSenwnL0Ha6BsXbJvUHRC5qcVlNy5Oq%2FpNqx2%2BKdwbw4eY7tZBDQhMKoaMVSbqbCb3eRBxxxx
Trace-Id: 0ba604b41558615600801371953814.0

The response body sample

copy
{
"result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
},
"paymentTime": "2019-05-28T12:12:13+08:00",
"paymentId":"1234567"
}

Validate a signature

Obtain the platform public key.
Construct the content to be validated ( Content_To_Be_Validated ).
Get the signature from the response header.
Validate the signature.

For details of each step, see the following examples.

Example

1. Obtain the platform public key

The Client-Id and KeyVersion properties can be obtained from the response header. Merchants send these properties to the wallet, based on which, the wallet returns the public key to the merchant.

2. Construct the content to be validated

Given the response body sample above, by complying with the Syntax of Content_To_Be_Validated, construct the content to be validated (Content_To_Be_Validated) as follows:

copy
POST /api/v2/payments/pay
TEST_5X00000000000000.2019-05-28T12:12:14+08:00.{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
 },
 "paymentTime": "2019-05-28T12:12:13+08:00",
 "paymentId":"1234567"
}

Syntax of `Content_To_Be_Validated`

copy
<HTTP_METHOD> <HTTP_URI>
<Client-Id>.<Response-Time>.<HTTP_BODY>

Client-Id : identifies a client. You can get this field from the response header. For example
TEST_5X00000000000000
Response-Time: Indicates the time when a response is returned, as defined by ISO8601. Note: This field must be accurate to milliseconds. You can get this field from the response header.
HTTP_BODY : Indicates the data body of the response.

3. Get the signature from the response header

The target signature string ( target_signature ) is extracted from Signature header of the response. For details about the response header, see the Message structure chapter.

copy
Signature: algorithm=RSA256, keyVersion=1, signature=<target_signature>

4. Validate the signature

Use the sha256withrsa_verify method to validate the signature of a response.

Syntax of the sha256withrsa_verify method:

copy
sha256withrsa_verify(base64UrlDecode(<target_signature>), <Content_To_Be_Validated>, <serverPublicKey>)

target_signature : the signature extracted from the response header, which is obtained from step 3.
Content_To_Be_Validated : the content to be validated that is created from step 2.
serverPublicKey : the platform public key that is obtained from step 1.

More information

Message structure