跳到主要内容

Payment / Withdraw

API Docking Specification

version 1.0.0

pagarstar.com

copyright reserved

May. 2023

Versions

Ver.EditorUpdate atDescription
v1.0.0Reymond2023-05-15First released

Declamation

The information contained in this document is a trade secret, and the company owns its patents (or is applying for a patent) for the technologies and products involved in the document, including copyrights for trademarks or other intellectual property rights.

Without the company's written authorization contract, no person shall obtain or hold this document in any way, and may not use part or all of the content of this document. Changes in the content of this document are subject to change at any time without notice.

Important note

  1. Please ask the CS team for the API Host URL
  2. The payment request is based on HTTPS protocol, only POST form is supported.
  3. The data is UTF-8 Encode.
  4. The parameters & participate in the signature must according to ASCII in order. Null values still need to be added to the signature.
  5. Please provide the Host IP to the CS team before docking for adding whitelist.
  6. All requests have specify header. Please follow the setting for the request header.

Request format

Please follow the guide below to produce your request:

  1. Prepare your request data and generate the signature.
  2. Convert the request body into JSON string.
  3. Encrypt the JSON string by AES-ECB-PKCS7. The encrypt key is your merchant safecode.
  4. Encode your encrypted string via base64_encode and get the final request string.
  5. Request Http Header Content-Type should be text/plain

Example

Signed Request Body

{
"order_id": "20210514183849",
"amount": "40000",
"currency": "PHP",
"timestamp": "1612245402",
"callback_url": "http://my.service/callback",
"redirect_url": "https://my.service/redirect",
"channel": "alipay",
"bank_code": "",
"remark": "test",
"user_id": "1",
"sign": "lOp6SoczkquxzYTDufsVTIjjTdKuCGZnGEa7…."
}

Json String

{"order_id":"20210514184046","amount":"40000","currency":"PHP","timestamp":"1612245402","callback_url":"http://my.service/callback","redirect_url":"https://my.service/redirect","channel":"alipay","bank_code":"","remark":"test","user_id":"1","sign":"lOp6SoczkquxzYTDufsVTIjjTdKuCGZnGEa7..."}

AES ECS Encrypted by safecode + base64_encode

wbTkX4OdkK8xqvrnqqKalTp/XiC+svRLvgu6UGQ5gDPx9iTRSS3ng8cRkLwfrxnN3Ba4YZAtMtb2PahMj0KNz56ovbuctKsMWMjztpIn2eLCHWNzVHRrU8eJ/aG0OgDztdceON2xBGYEtzpyf1Lc9jycfnd35tANhZgWFlNvCPrTNsbTjrVA3fH1gOKzn35CfHsuyWertBQjp/FqMkDWa7G1gRxXa2L1s...

Response format

Service response (or callback) will follow this format:

Request header

ParameterContent
Content-Typeapplication/json

Request body

ParameterData TypeRequiedDescription
codestringYesStatus code. Success will return "1000", and other numbers are failure indexes.
messagestringYesResult description
dataarrayNoResult data will be provided when "code" is "1000".

Signarue rules

Before generate signature, please make sure the following information ready:

  • Get your merchant safecode
  • Get your RSA key pair. (Your can generate it via our service, or by your own)
  • Your RSA public key is uploaded to our service

Signature produce steps:

  1. Sort your request parameters by key in ASCII order. Concate each parameter's key and value by equal(=) symbol, then join all parameters by and(&) symbol. At last, append "&" and your merchant safecode at the end of the sign string. EXAMPLE: amount=1&channel=alipay¤cy=PHP&merchantid=123456&mid=1¬ifyurl=www.abc.com/callback&returnurl=www.abc.com/returnurl&service=Payment &safecode
  2. Encrypt the sign string by SHA256 and your merchant private key
  3. Encode encrypted string by base64 to get your final signature.

Signature verify rules

Before verify signature, please make sure the following information ready:

  • Get your merchant safecode
  • Get our service platform public key

Signature verification steps:

  1. Sort response parameters except signature by key in ASCII order. Concate each parameter's key and value by equal(=) symbol, then join all parameters by and(&) symbol. At last, append "&" and your merchant safecode at the end of the "verification string". Note: Except the sign field, other parameters should participate in the verification string.
  2. Get signature from response then using base64 decode to get binary signature
  3. Verify binary signature by platform public key and verification string. Encryption rule is SHA256.

Two stages request rule

For system security purposes, you should provide a verification token in the HTTP request header.

Step 1. fetch random code

At the beginning of the request process, you should fetch a random code from our service. This random code will expire in 30 seconds.

API URL: /merchant/random_code

Request

Request header

ParameterContent
Content-Typeapplication/json

Request body

ParameterData typeRequiedDescription
user_idStringYesMerchant identification

Response

Response body

ParameterData typeRequiedDescription
codeStringYesThe random code to fetch verify token

Example

{
"code": "1000",
"message": "Accepted",
"data": {
"code": "VL4hrMLmM3THd2iQDNOoa45cGZhx2zH7"
}
}

2. Get verification token

You can get the verification token via the following process.

API URL: /merchant/token

Request header

ParameterContent
Content-Typeapplication/json

Request body

ParameterData typeRequiedDescription
user_idStringYesMerchant identification
hashStringYesVerification hash string.

How to produce verification hash string:

  1. Concat {random_code} {user_id} {safecode} in given order without any separator or whitespace.
  2. Put the concatenated string into SHA256 Hash and get your hash code.

Response body

ParameterData typeRequiedDescription
access_tokenStringrYesthe token to put into your request header
token_typeStringYesthe type of token
expires_inIntergeYestoken expire time in second

Example:

{
"code": "1000",
"message": "Accepted",
"data": {
"access_token": "cyJacasxzxc...",
"token_type": "bearer",
"expires_in": 300
}
}

Payment Request

API URL: /merchant/payment

Request

Request header

ParameterContentDescription
Content-Typetext/plaintext
Authorization{token_type} {access_token}Please concat token_type and access_token with whitespace

Request body

ParameterData typeRequiedSignDescription
user_idStringYesYesMerchant identification
order_idStringYesYesYour order id. The order id should be unique.
amountStringYesYesTransaction amount (Support up to 6 decimal places)
currencyStringYesYesSupported currencies please refer Annex 1
channelStringYesYesSupported channels please refer Annex_1
bank_codeStringOptionalYesREQUIRED if the channel is "bank2bank".If this parameter is provided, you need to add it to the sign string.Please go to the background page-API Docking, download and refer to the bank list.
real_nameStringOptionalNoComply with Chinese government regulations, required for RMB transactions.
callback_urlURLYesYesService will send a callback request to this URL when the transaction completes.
redirect_urlURLYesYesWhen the payment process finishes, the client will be redirected to this URL.
timestampIntegerYesYesRequest timestamp (10 digits)
remarkStringNoNoremark
signStringYesNoSignature string

Response

There are three type of payment response methods:

  • Redirect - return redirect javascript, then player will be redirected to payment webpage.
  • HTML - return a html and submit it automatically.
  • JSON - return request result in JSON format (only response code = 1000)
Response body (JSON only)
Parameter
user_id
order_id
transaction_id
channel
submit_currency
submit_amount
accept_currency
accept_amount
exchange_rate
pay_url
wallet_address
expired_at
sign

Example

{
"code": "1000",
"message": "Accepted",
"data": {
"user_id": 1,
"order_id": "20210521184906",
"transaction_id": "P12021052118495503889",
"channel": "PHP2TRC",
"submit_currency": "PHP",
"submit_amount": 1000,
"accept_currency": "USDT-TRC",
"accept_amount": 165.9181999999,
"exchange_rate": 0.1659182,
"sign": "jgtOKfV48sOD2NjBZ4WhiAUMwTgux9fTH53jNzNR..."
}
}

Go to Cashier

If you set the channel to "cashier", the system will return the URL to the cashier. Here is an example:

{
"cashier_url": "http://example.com/cashier?order_id=TP20210715135507&token=3281DCF1C8A6D7AFA0B96CFDD874F417"
}

Callback Request (Service to merchant)

Request header

ParameterContent
Content-Typeapplication/json

Request body

ParamterData typeRequiredSignDescription
user_idStringYesYesMerchant identification
order_idStringYesYesYour order id. The order id should be unique.
transaction_idStringYesYesOur service transaction id
channelStringYesYesSupported channels please refer Annex_1
submit_currencyStringYesYesSubmit currency
submit_amountFloatYesYesSubmit amount (Support up to 6 decimal places)
accept_currencyStringYesYesThe currency real paid
accept_amountFloatYesYesPaid amount of accept currency (Support up to 6 decimal places)
exchange_rateFloatYesYesExchange rate
statusStringYesYes0000 = Waiting1000 = Processing2000 = Success3000 = Failed4000 = Order error
timestampIntegerYesYesTransaction last update timestamp (10 digits)
submit_promoFloatNoNoSubmit amount promo(Support up to 6 decimal places)
accept_promoFloatNoNoPaid amount promo of accept currency (Support up to 6 decimal places)
payment_addressStringNoNoCrypto exclusive, if need, please inform customer service staff
receiving_addressStringNoNoCrypto exclusive, if need, please inform customer service staff
signStringYesNoSignature string

Callback Result

Please return the string " SUCCESS" when callback is received. If there is anything wrong, please return the string " FAILED".

Payment Order

API URL: /merchant/order/payment

Request

Request header

ParameterContentDescription
Content-Typetext/plaintext
Authorization{token_type} {access_token}Please concat token_type and access_token with whitespace

Request body

ParamterData typeRequiredSignDescription
user_idStringYesYesMerchant identification
order_idStringYesYesYour order id. The order id should be unique.
return_hashBooleanNoNoWhether to return the transaction hash.
signStringYesNoSignature string

Response

Response body

ParamterData typeRequiredSignDescription
user_idStringYesYesMerchant identification
order_idStringYesYesYour order id. The order id should be unique.
transaction_idStringYesYesOur service transaction id
channelStringYesYesSupported channels please refer Annex_1
submit_currencyStringYesYesSubmit currency
submit_amountFloatYesYesSubmit amount (Support up to 6 decimal places)
accept_currencyStringYesYesThe currency real paid
accept_amountFloatYesYesPaid amount of accept currency (Support up to 6 decimal places)
exchange_rateFloatYesYesExchange rate
statusStringYesYes0000 = Waiting1000 = Processing2000 = Success3000 = Failed4000 = Order error
timestampIntegerYesYesTransaction last update timestamp (10 digits)
submit_promoFloatNoNoSubmit amount promo(Support up to 6 decimal places)
accept_promoFloatNoNoPaid amount promo of accept currency (Support up to 6 decimal places)
hashStringNoNoTransaction hash.(Provided when return_hash = true)
payment_addressStringNoNoCrypto exclusive, if need, please inform customer service staff
receiving_addressStringNoNoCrypto exclusive, if need, please inform customer service staff
signStringYesNoSignature string

Example

{
"code": "1000",
"message": "Order Success",
"data": {
"user_id": 1,
"order_id": "20210521184906",
"transaction_id": "P12021052118495503889",
"channel": "PHP2TRC",
"submit_currency": "PHP",
"submit_amount": "1000.0000000000",
"accept_currency": "USDT-TRC",
"accept_amount": "165.9181999999",
"exchange_rate": "0.1659182000",
"status": "1000",
"timestamp": 1621594195,
"sign": "mG6FFzJvVh8DpQJpMUPWH619CelyDZgkgnty2HW..."
}
}

Withdraw Request

API URL: /merchant/withdraw

Request

Request header

ParameterContentDescription
Content-Typetext/plaintext
Authorization{token_type} {access_token}Please concat token_type and access_token with whitespace

Request body

ParameterData typeRequiredSignDescription
user_idStringYesYesMerchant identification
order_idStringYesYesYour order id. The order id should be unique.
amountStringYesYesTransaction amount (Support up to 6 decimal places)
currencyStringYesYesSupported currencies please refer Annex 1
channelStringYesYesSupported channels please refer Annex_1
card_noStringYesYesWithdraw card number.If your channel is running virtual currency, then put the wallet address here.
card_nameStringYesYesCard (Virtual wallet) owner's name
card_typeIntegerYesYes1 = private 2 = public
bank_codeStringYesYesPlease go to the background page-API Docking, download and refer to the bank list.
bank_nameStringYesYesPlease go to the background page-API Docking, download and refer to the bank list.
bank_branchStringYesYesBank branch(Limited length: 20, a Chinese word length is 2)
bank_provinceStringYesYesBank province(Limited length: 20, a Chinese word length is 2)
bank_cityStringYesYesBank city(Limited length: 20, a Chinese word length is 2)
cnaps_codeStringYesYesBank lines. REQUIRED when card_type = 2.
callback_urlURLYesYesService will send a callback request to this URL when the transaction completes.
timestampIntegerYesYesRequest timestamp (10 digits)
remarkStringNoNoremark
signStringYesNoSignature string

Response

Response body

ParameterData typeRequiredSignDescription
user_idStringYesYesMerchant identification
order_idStringYesYesYour order id. The order id should be unique.
transaction_idStringYesYesOur service transaction id
channelStringYesYesSupported channels please refer Annex_1
submit_currencyStringYesYesSubmit currency
submit_amountFloatYesYesSubmit amount (Support up to 6 decimal places)
accept_currencyStringYesYesThe currency real paid
accept_amountFloatYesYesPaid amount of accept currency (Support up to 6 decimal places)
exchange_rateFloatYesYesExchange rate
signStringYesNoSignature string

Example

{
"code": "1000",
"message": "Accepted",
"data": {
"user_id": 1,
"order_id": "20210521181858",
"transaction_id": "W12021052118190115910",
"channel": "PHP2ERC",
"submit_currency": "PHP",
"submit_amount": 40000,
"accept_currency": "USDT-ERC",
"accept_amount": 6644,
"exchange_rate": 0.1661,
"sign": "hZJiccj0EPEQkoOlsmkRWEzHZ+dvbgD8t2RyNzL..."
}
}

Callback Request (Service to merchant)

Request header

ParameterContent
Content-Typeapplication/json

Request body

ParameterData typeRequiredSignDescription
user_idStringYesYesMerchant identification
order_idStringYesYesYour order id. The order id should be unique.
transaction_idStringYesYesOur service transaction id
channelStringYesYesSupported channels please refer Annex_1
submit_currencyStringYesYesSubmit currency
submit_amountFloatYesYesSubmit amount (Support up to 6 decimal places)
accept_currencyStringYesYesThe currency real paid
accept_amountFloatYesYesPaid amount of accept currency (Support up to 6 decimal places)
exchange_rateFloatYesYesExchange rate
statusStringYesYes0000 = Waiting1000 = Processing2000 = Success3000 = Failed4000 = Order error
timestampIntegerYesYesTransaction last update timestamp (10 digits)
signStringYesNoSignature string

Callback Result

Please return the string " SUCCESS" when callback is received. If there is anything wrong, please return the string " FAILED".

Withdraw Query

API URL: /merchant/order/withdraw

Request

Request header

| Parameter | Content | Description | | Content-Type | text/plain | text | | Authorization | {token_type} {access_token} | Please concat token_type and access_token with whitespace |

Request body

ParameterData typeRequiredSignDescription
user_idStringYesYesMerchant identification
order_idStringYesYesYour order id. The order id should be unique.
return_hashBooleanNoNoWhether to return the transaction hash.
signStringYesNoSignature string

Response

Request body

ParameterData typeRequiredSignDescription
user_idStringYesYesMerchant identification
order_idStringYesYesYour order id. The order id should be unique.
transaction_idStringYesYesOur service transaction id
channelStringYesYesSupported channels please refer Annex_1
submit_currencyStringYesYesSubmit currency
submit_amountFloatYesYesSubmit amount (Support up to 6 decimal places)
accept_currencyStringYesYesThe currency real paid
accept_amountFloatYesYesPaid amount of accept currency (Support up to 6 decimal places)
exchange_rateFloatYesYesExchange rate
statusIntegerYesYes0000 = Waiting1000 = Processing2000 = Success3000 = Failed4000 = Order error
timestampIntegerYesYesTransaction last update timestamp (10 digits)
hashStringNoNoTransaction hash.(Provided when return_hash = true)
signStringYesNoSignature string

Example

{
"code": "1000",
"message": "Order Success",
"data": {
"user_id": 1,
"order_id": "20210521181858",
"transaction_id": "W12021052118190115910",
"channel": "PHP2ERC",
"submit_currency": "PHP",
"submit_amount": "40000.0000000000",
"accept_currency": "USDT-ERC",
"accept_amount": "6644.0000000000",
"exchange_rate": "0.1661000000",
"status": "1000",
"timestamp": 1621592342,
"sign": "OKmzL8zt5w10YLu4scOmQ6R0yOXKo+/XLdAo7ZbAyz..."
}
}

Withdrawal confirmation

(service to merchant)

Our service provides a withdrawal confirmation function. You can use it to double-check the withdrawal request was sent from you. While withdrawal confirmation is enabled, our system will send a withdrawal confirmation for each withdrawal request we received to the URL you given to us. If this withdrawl request is confirmed, then the transaction will continue. Otherwise, the withdrawal request will be halted and mark it as an anomaly.

If you want to use our withdrawal confirmation function, please contact our customer service team. Also, you need to implement the API described below and provide your confirmation URL to us.

Request

Request header

ParameterContent
Content-Typeapplication/json

Request body

ParameterData typeRequiredSignDescription
user_idStringYesYesMerchant identification
order_idStringYesYesYour order id. The order id should be unique.
amountIntegerYesYesTransaction amount (Support up to 6 decimal places)
timestampIntegerYesYesThe timestamp which provides within withdraw request (10 digits)
signStringYesNoSignature string

Response

Response body

ParameterData typeRequiredSignDescription
user_idStringYesYesMerchant identification
order_idStringYesYesYour order id. The order id should be unique.
confirmStringYesYesReturn "SUCCESS" indicated order confirmed. Other values indicate failure.
signStringYesNoSignature string

Balance query

API URL: /merchant/balance

Request

Request header

| Parameter | Content | Description | | Content-Type | text/plain | text | | Authorization | {token_type} {access_token} | Please concat token_type and access_token with whitespace |

Request body

ParameterData typeRequiredSignDescription
user_idStringYesYesMerchant identification
typeIntegerNoNoDefault value is 0 if you don't send this field.0 = the returned balance value indicates the current amount in our system.1 = the returned balance value indicates the balance that can be withdraw (Not included the amount that sent withdraw request but not success yet)
signStringYesNosignature string

Response

Response body

ParameterData typeRequiredSignDescription
user_idStringYesYesMerchant identification
PHPArrayNoNoRMB currency = { channel_name: channel_balance}(Support up to 6 decimal places)
USDT-TRCArrayNoNoUSDT-TRC currency = { channel_name: channel_balance}(Support up to 6 decimal places)
{currency}ArrayNoNoAny other currencies supported by our service.
signStringYesNoSignature string

Example

{
"code": "1000",
"message": "Accepted",
"data": {
"user_id": 1,
"USDT-TRC": {
"PHP2TRC": 50000,
"TRC": 50000.324132
},
"USDT-ERC": {
"PHP2ERC": 50000,
"ERC": 50000
},
"sign": "QHnRBlfzyIa72eaQmUGTfPCVNKLzels+..."
}
}

Exchange rate query

API URL: /merchant/rate

Request

Request header

| Parameter | Content | Description | | Content-Type | text/plain | text | | Authorization | {token_type} {access_token} | Please concat token_type and access_token with whitespace |

Request body

ParameterData typeRequiredSignDescription
user_idStringYesYesMerchant identification
trade_currencyStringYesYesSupported currencies please refer Annex 1
signStringYesNoSignature string

Response

Response body

ParameterData typeRequiredSignDescription
user_idStringYesYesMerchant identification
trade_currencyStringYesYesSupported currencies please refer Annex 1
{currency}ArrayNoNoAny other currencies supported by our service.
signStringYesNoSignature string

Example

{
"code": "1000",
"message": "Accepted",
"data": {
"user_id": "1",
"trade_currency": "PHP",
"USDT-ERC": {
"payment": 6.51,
"withdraw": 6.51
},
"USDT-TRC": {
"payment": 6.6,
"withdraw": 6.6
},
"sign": "n8g5tDELHuzLNX9tmqLA3O1aT6hnNti64..."
}
}

Annex 1: Currencies and Channels

Note: set channel to "cashier" will be redirect to cashier

CurrencyDescriptionSupported channels
PHPRMB- cashier
- bank2bank
- alipay2alipay
- alipay2bank
- alipayqrcode
- PHP2ERC
- PHP2TRC
- PHP2USDC
- PHP2ETH
USDTUSDT- cashier
USDT-ERCUSD Token ERC20- ERC
USDT-TRCUSD Token TRC20- TRC
USDCUSD Coin- USDC

Annex 2: Error codes

Error codesError message
1000Request accepted
1001Request field not valid
1002Transaction not found
1003Duplicate order id
1004Payment exceed quota limit
1005Withdraw amount too large
1006Withdraw amount too small
1007Not enough balance
1008Not supported currency
1009Unauthorized request
1010Signature check failed
1011This service does not supported
1012Token verify failed
1013Insufficient balance for withdrawal
1014Insufficient balance for exchange
1015Currency does not match the channel configuration
1016API token expired
1017Request data decryption failed
1018Whitelist not allow this IP
1019Withdraw confirm failed
1020Request not valid
1021Payee not found
1100Invalid account or password
4001Upstream request failed
4002Upstream return unsuccessful
4003Upstream response check failed
4004Upstream does not support this bank
4005Upsteam require cnaps code
8001Service not available
8002Gateway not available
8003Exceed quota limit
8004Below quota limit
8005Upstream API not ready
8006Payment return type not support
8007Request IP not allowed
8008Exchange rate not available
8010Balance hold failed
8011Couldn't find merchant info
8012Couldn't find admin info
8013Request validation failed
8101Gateway not configured
8102Gateway not enabled
8103User gateway not configured
8104User gateway not enabled
8105Upstream not enabled
8106Cannot get user safecode
8107Cannot get user public key
8108Gateway not found
9000Upstream api not ready
9001Request rule invalid
9002Response decode failed
9003Callback rule invalid
9004Can not get user balance
9005Gateway not found
9006Service config not ready
9007Gateway request error
9008System private key not ready
9009Return data not valid
9999Unrecognized server error