SparkPay OpenAPI Docs
English
  • English
  • 简体中文
English
  • English
  • 简体中文
  1. Quick Guide
  • Product Introduction
  • Quick Guide
    • Integration Preparation
    • Interface Signature Description
  • Must-Read for Integration
    • Interface Rules
    • Asynchronous Notification
    • Interface Error Codes
    • Network and Currency
  • Integration Scenarios
    • Payment
    • Close Order
  • API List
    • Payment Order Creation
      POST
    • Payment Order Query
      GET
    • Payment Order Closure
      POST
    • Payment Order Creation(Pro Edition)
      POST
    • Payment Order Query(Pro Edition)
      GET
  • Frequently Asked Questions
    • Notification Related Issues
    • Redirect Failure Issues
    • Interface Error Issues
    • Test Token Acquisition/Test Network Connection
  • Integration Example
    • Interface Signature Example - PHP
    • Interface Signature Example - Postman
  • Version Notes
    • Version Notes
  1. Quick Guide

Interface Signature Description

Interface signing refers to the process where, when calling the SPARK OpenAPI, the application must use public and private keys to sign and verify the content of messages to ensure the security and authenticity of the communication between both parties.
Developers need to prepare a pair of RSA public and private keys (2048 bits, Base64 encoded, with the keys generated in PKCS#8 format and the public key in X.509 format) and upload the RSA public key via the SPARK merchant backend. The payment platform will verify it, and once approved, it can be used.
At the same time, the SPARK platform will also provide the payment platform public key for the merchant application to sign and verify the data returned from the payment platform. The process for requests and verification is as follows:
1.
Request parameters: Encoded in UTF-8, type is String.
2.
Before sending the request business message, the merchant application needs to sign the message using its own RSA private key.
3.
After the request is successful, the merchant application must verify the response message using the payment platform public key.

Third-Party Tools for Generating Public and Private Keys#

When uploading the merchant public key, if the generated public and private key content does not include standard prefixes or suffixes, these need to be added in the standard format.
Visit https://www.devglan.com/online-tools/rsa-encryption-decryption and select 2048 bits to automatically generate a pair of public and private keys.

Signing Algorithm#

Introduction to RSA: https://en.wikipedia.org/wiki/RSA_(cryptosystem)
Introduction to RSA signature algorithms: https://cryptobook.nakov.com/digital-signatures/rsa-signatures

Generate Request Signature#

1.
Preparation
Log in to the merchant platform and go to the “Applications” page to view the merchant application's AppID.
After uploading the merchant RSA public key, the corresponding RSA private key needs to be used for signing.
2.
Construct Signature String
The request message body is constructed based on request parameters, formatted in JSON.
Please construct the request signature string according to the format ('Request Timestamp\n' + 'Request Random String\n' + 'Request Message Body\n'). Note that \n denotes a new line.
3.
Calculate Signature Value
Most programming languages provide signing functions that support signing data. It is strongly recommended that merchants call these functions, using their private key to perform SHA256 with RSA signing on the string to be signed and Base64 encode the signing result to obtain the signature value.
4.
Set HTTP Headers
HTTP HeaderDescription
Sparkpay-App-IdMerchant Application ID
Sparkpay-NonceRequest random string; should not repeat for the same merchant application ID within 5 minutes, otherwise, the open API will reject this request.
Sparkpay-TimestampRequest timestamp (accurate to the second)
Sparkpay-SignatureSignature value

Note:#

The merchant application uses its own RSA private key to sign the JSON string of the request parameters.
The signature value uses standard Base64 encoding.

Verify Signature#

1.
Preconditions
Obtain the payment platform public key by logging into the merchant platform and visiting the “Applications” page for download.
2.
Prevent Replay Attacks
To reduce the risk of replay attacks, the timestamp for generating the signature is provided in the HTTP header Sparkpay-Timestamp. If it is necessary to resend a request, Spark payment will regenerate the corresponding timestamp and signature.
Before validating the signature, the merchant system should check whether the timestamp has expired. We recommend allowing a maximum of 5 minutes for timestamp deviation. If the deviation between the timestamp and current time exceeds 5 minutes, you should reject the processing of the current response.
3.
Construct Verification Signature String
The value in the HTTP header Sparkpay-Timestamp is the response timestamp (accurate to the second).
The value in the HTTP header Sparkpay-Nonce is the response random string.
For the response message body, execute the verification using the response message body. Any tampering with the message body will cause verification to fail.
Then, please construct the response verification signature string according to the format ('Response Timestamp\n' + 'Response Random String\n' + 'Response Message Body\n').
4.
Obtain Response Signature
The value in the HTTP header Sparkpay-Signature is the signature value.
5.
Verify Signature
Most programming languages provide signature verification functions that support verifying the signature string and the signature. It is strongly recommended that merchants call these functions, using their private key to perform SHA256 with RSA signature verification on the verification signature string and the signature.
Modified at 2024-09-12 02:03:31
Previous
Integration Preparation
Next
Interface Rules
Built with