Mini Program Development PlatformMini Program Development PlatformDOCS

Call an API via adding a signature

before calling an API, signing a request is needed.

Sign a request

Procedures

  1. Obtain your private key, represented by privateKey, which is used to sign a request.
  2. Construct the content to be signed (Content_To_Be_Signed).
  3. Calculate and generate the signature.
  4. 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/v2/payments/pay
  • Client-Id : TEST_5X00000000000000
  • Merchant-Id: TEST_MERCHANT00000000000000
  • Request-Time : 1682060290199
  • 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.TEST_MERCHANT00000000000000.1682060290199.{
"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>.<Merchant-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, a timestamp.
  • HTTP_BODY : the data body of a request.

3. Calculate and generate the signature

Use thesha256withrsamethod 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, RSA256.

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=0, 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=0, 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 'Merchant-Id: TEST_MECHANT00000000000000' \
  -H 'Request-Time:  1682060290199' \
  -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"
       } 
}'

More informationes.

Message structure