Call an API via adding a signature
Before calling an API, signing a request is needed. After sending the request and obtaining the response, need to validate the response signature accordingly.
Sign a request
Procedure
- 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 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/v1/payments/payClient-Id
: TEST_5X00000000000000Request-Time
 : 2019-05-28T12:12:12+08:00HTTP_BODY
: the body looks like the following format.
{
"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:
POST /api/v1/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"
}
}
3. Calculate and generate the signature
Use the sha256withrsa
 method that involve the proper algorithm and private key to calculate and generate the signature.
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, RSA256.
For example, the generated signature generatedSignature
 looks as follows:
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.
'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:
'Signature: algorithm=RSA256, keyVersion=0, signature=KrwDE9tAPJYBb4cUZU6ALJxGIZgwDXn5UkFPMip09n%2FkYKPhEIII%2Fki2rYY2lPtuKVgMNz%2BtuCU%2FjzRpohDbrOd8zYriiukpGAxBQDIVbatGI7WYOcc9YVQwdCR6ROuRQvr%2FD1AfdhHd6waAASu5Xugow9w1OW7Ti93LTd0tcyEWQYd2S7c3A73sHOJNYl8DC1PjasiBozZ%2FADgb7ONsqHo%2B8fKHsLygX9cuMkQYTGIRBQsvfgICnJhh%2BzXV8AQoecJBTrv6p%xxxx'
b. Add the signature string to the request header.
For example:
-H 'Signature: algorithm=RSA256, keyVersion=0, signature=KrwDE9tAPJYBb4cUZU6ALJxGIZgwDXn5UkFPMip09n%2FkYKPhEIII%2Fki2rYY2lPtuKVgMNz%2BtuCU%2FjzRpohDbrOd8zYriiukpGAxBQDIVbatGI7WYOcc9YVQwdCR6ROuRQvr%2FD1AfdhHd6waAASu5Xugow9w1OW7Ti93LTd0tcyEWQYd2S7c3A73sHOJNYl8DC1PjasiBozZ%2FADgb7ONsqHo%2B8fKHsLygX9cuMkQYTGIRBQsvfgICnJhh%2BzXV8AQoecJBTrv6p%xxxx'
Syntax of Content_To_Be_Signed
<HTTP_METHOD> <HTTP_URI>
<Client-Id>.<Request-Time>.<HTTP_BODY>
HTTP_METHOD
: POSTHTTP_URI
: For example, if the HTTP URL is https://example.com/api/v1/payments/pay, this property is/api/v1/payments/pay
.Client-Id
: is used to identify a client, and is associated with the keys that are used for signature and encryption. You can get this field from the request header.Request-Time
: Specifies the time when a request is sent, as defined by RFC3339. 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.
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.
curl -X POST \
https://example.com/api/v1/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 response body. For example:
- The response header sample
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
{
"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:
POST /api/v1/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"
}
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.
Signature: algorithm=RSA256, keyVersion=0, 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:
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.
Syntax of Content_To_Be_Validated
Â
<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 exampleTEST_5X00000000000000
Response-Time
: Indicates the time when a response is returned, as defined by RFC3339. 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.