Quick with RedotPay Connect RESTful APIs

Key Updates
This document has been updated for the latest API version:

secretKey Removed: The secretKey is no longer used for signature verification in the new API version.

Request Header Updated: The authentication header has been renamed from X-Merchant-Ak to X-R-AK.

New Required Header: The X-R-KEY-VERSION header is now required to specify the key version used for signing.

RedotPay Connect provides RESTful APIs based on the HTTP protocol, using JSON for requests and responses. It is designed to help merchants integrate payment services quickly and securely.

Calling the API

To successfully call the RedotPay API, you need to complete the following preparations: obtain API credentials, understand the request signature mechanism, and conduct thorough testing in the sandbox environment first.

Step 1: Obtain Your appKey and Configure Key Pair

Before calling the API, you need to obtain the appKey for authentication. Also, to sign requests using the SHA256withRSA algorithm, you need to generate and configure your own RSA key pair.

Field	Description	Provider
`appKey`	The unique identifier for your merchant account.	RedotPay

To simplify the process, we provide a pre-configured test appKey that you can use directly for interface testing without immediately applying for production credentials.

Test Credentials in API Reference

Credential Type	Value	Description
`appKey`	`4CA7B705-8EF5-4AC3-A0B6-9A4B84EF13B6`	Pre-issued test appKey for quick setup.

Obtain Sandbox AppKey
Before processing live transactions, test in the sandbox environment. You can obtain sandbox credentials from the RedotPay Connect Platform:

Register your merchant account.
Complete Know Your Customer (KYC) and Know Your Business (KYB).
Check and configure your appKey in the Developer menu.

Step 2: Transmit Credentials and Signatures in Headers

All API requests must include specific HTTP headers for authentication, security, and signature validation. The following table defines all required and relevant request headers:

Header Name	Description	Required	Format / Constraints	Example
`X-R-AK`	Your merchant appKey for account identification and authentication.	Yes	String (UUID format)	`4CA7B705-8EF5-4AC3-A0B6-9A4B84EF13B6`
`X-R-TS`	The timestamp (in milliseconds) when the request is generated. Used to prevent replay attacks.	Yes	Unix Epoch in milliseconds. Server validates its validity within a tolerance window.	`1763555087656`
`X-R-KEY-VERSION`	Indicates the version of the key pair used to generate the request signature, facilitating key rotation.	Yes	Natural number (e.g., 1, 2, 3...). Must match the version of the private key used for signing.	`1`
`X-R-Signature`	The digital signature of the request, ensuring its integrity and authenticity.	Yes*	Base64-encoded string, generated using the SHA256withRSA algorithm as defined in the separate Signature guide.	`ZxAmLpVyzQ...` (abbreviated)
`Content-Type`	Standard HTTP header specifying the media type of the request body.	Yes	Fixed value: `application/json`	`application/json`

Note: The X-R-Signature header is mandatory for all requests containing a body in Production and Gray environments. For testing purposes in the sandbox or the "Try It Out" interface, signature verification may be disabled.

Request Example
The following example shows how to include these headers in a typical API call:

POST /openapi/v2/order/create HTTP/1.1
Host: api-sandbox.redotpay.com
Content-Type: application/json
X-R-AK: 4CA7B705-8EF5-4AC3-A0B6-9A4B84EF13B6
X-R-TS: 1763555087656
X-R-KEY-VERSION: 1
X-R-Signature: ZxAmLpVyzQEGBE5fC6bqLq7KjRzP5HdVoT4nLkP8x7c=... (full signature)

{
  "orderId": "TEST_ORDER_001",
  "amount": "88.88",
  "currency": "USD"
}

For detailed instructions on how to generate the X-R-Signature and manage key versions, please refer to the separate Signature Documentation.

Step 3: Understand API Endpoints and Environments

Environments and Request URLs
RedotPay Connect provides two environments: Sandbox and Production. Their API paths (Endpoints) are generally consistent, with the main difference being the domain name (host address).

Environment	Purpose	Request URL Format
Sandbox	Functional testing and integration	`https://tenv-acquirer.rp-2023app.com/{endpoint}`
Production	Live transaction processing	`https://acquirer.redotpay.com/{endpoint}`

Note: The specific sandbox and production domain names can be obtained from the RedotPay Connect platform or the relevant configuration guide. You should complete all testing in the sandbox environment before switching to production.

Step 4: View Complete Request and Response Examples

A typical API interaction example is as follows:

Request Example

POST /openapi/v2/order/create HTTP/1.1
Host: api-sandbox.redotpay.com
Content-Type: application/json
X-R-AK: 4CA7B705-8EF5-4AC3-A0B6-9A4B84EF13B6
X-R-TS: 1763555087656
X-R-KEY-VERSION: 1
X-R-Signature: 5415c7bcc8c93e5f... (example, actual is longer)

{
  "orderId": "TEST_ORDER_001",
  "amount": "88.88",
  "currency": "USD"
}

Successful Response Example

{
  "code": "SUCCESS",
  "msg": null,
  "data": {
    "orderSn": "P20250125123000123456",
    "outerOrder": "TEST_ORDER_001",
    "h5Url": "https://pay.redotpay.com/checkout/..."
  }
}

Error Response Example

{
  "code": "signError",
  "msg": "sign verify failed",
  "data": null
}

Try It Out

You can directly try calling the API in the API Reference using your own appKey or our provided test credentials.

Important: The request signature is NOT verified in the "Try It Out" interface of the API Reference. This feature is only for convenient quick testing. You must correctly implement the signature logic for actual production integration.