Tarspay
    Tarspay
    • Indonesia🇮🇩
    • Vietnam🇻🇳
    • India🇮🇳
    • Malaysia🇲🇾
    • Egypt🇪🇬
    • Thailand🇹🇭
    • Philippines🇵🇭
    • Brazil🇧🇷
    • Mexican🇲🇽
    • Kenya🇰🇪
    • Bengal🇧🇩
    • Pakistan🇵🇰

    Pakistan🇵🇰

    Interface Description#

    This article is intended for: technical architects, R&D engineers, and system operation and maintenance engineers who use the Tarspay merchant self-service system. Through this document, merchants can understand the technology connected to Tarspay, the products and businesses connected, the access process, access specifications and other information, so that merchants can successfully complete the access work.

    Access flow chart#

    privateKey (private key): The merchant keeps it by himself and does not disclose it. The merchant uses this private key to sign the order information when placing an order on behalf of the merchant.
    publicKey (public key): The merchant needs to upload the key to our platform (merchant backend-account management-apiKey menu), and when you call our interface, you need to include the request header X-API-KEY carries your public key, and we use this public key to verify that the message is signed by your private key.
    System publicKey: We will inform you to use the transaction status verification. When we send the callback transaction status notification, we will carry the signature information X-RESP-SIGNATURE in the request header. You can use it. The system publicKey verification message is sent by us.

    common problem#

    1.
    The interface returns error description "You have not bound or opened the API Key. Please verify whether the publicKey is consistent with the calling environment, and whether X-API-KEY has passed in the correct public key."
    2.
    The interface returns the error description "sign error". Please verify whether the public and private keys are a pair and whether there is any problem with the signature algorithm. Currently, the Java version signature verification tool class is provided at the bottom of the document.
    3.
    The interface returns the error description "MERCHANT_FEE_CONFIG_NOT_INIT", please contact our operation configuration

    Signature algorithm#

    Tarspay uses [ECDSA signature tool class](#signature tool class) signature for verification. After you open an account in Tarspay, you can generate a public and private key pair locally, or you can generate your public and private key through the Tarspay Web management interface. If you have any questions, you can also contact our staff to assist you. You can enter your public key through the Tarspay web management interface. Please keep your private key properly and do not disclose it to anyone to avoid asset loss! Tarspay strongly recommends that you bind your IP address to the whitelist.
    Tarspay's API requests, except for public APIs, need to carry API key and signature
    The data prepared before signing is as follows:
    HTTP_METHOD + | + HTTP_REQUEST_PATH + | + TIMESTAMP + | + PARAMS
    After the connection is completed, the data is ECDSA signed, and the signed bytes are Hex encoded.

    HTTP_HOST#

    Prod: https://payment.tarspay.com

    HTTP_METHOD#

    GET, POST need to be capitalized

    HTTP_REQUEST_PATH#

    The PATH part of the request URL, for example: https://payment.tarspay.com/api/v1/test is /api/v1/test

    NONCE#

    UNIX EPOCH timestamp (accurate to milliseconds) when accessing the API

    PARAMS#

    First sort the keys alphabetically, and then parameterize the url, that is, password=password username=username. Because p is sorted before u in the alphabet, password must be placed before username, and then use & to connect, that is: password =password&username=username The request parameters are the same for POST and GET. All parameters need to be taken out. The signature rules are as follows: All requested keys are sorted in alphabetical order, and then spliced in the form of key=value (the value does not require urlencode), and Use & to connect.

    Complete example#

    For the following requests:
    MethodURLNonce
    POSThttps://payment.tarspay.com/api/v1/test1537498830736
    parameter
    Parametervalue
    amount100
    price100
    The preparation data before signing is as follows:
    1.
    Assume that all data sent or received is a set M, and the parameters with non-empty parameter values in the set M are sorted from small to large according to the ASCII code of the parameter name (lexicographic order), using the format of URL key-value pairs (i.e. key1=value1&key2 =value2...) concatenated into a string:
    Tip: content does not require URLEncode
    2.
    Splice the concatenated string content and method request information MERTHOD, URL and NONCE into a new string separated by "|":
    3.
    Use the private key you generated (PrivateKey) to perform ECDSA signature on the spliced data, and Hex encode the binary result to generate the final signature for verification to the API server.
    Put the Api key, nonce and signature generated on the right into the Header according to the above name, and you can pass the signature verification.
    The Tarspay signature verification public key can be obtained from the "Web Management Interface - Account Management - apikey" page

    Return description#

    Return results
    NameTypeDescription
    codeintegerResponse code 0 indicates success, otherwise failure
    dataobjectresponse data
    msgstringResponse message
    Return to example
    {
    "code": 0,
    "data": {},
    "msg": "SUCCESS"
}

    Collection#

    POST collection and unified order placement#

    POST HTTP_HOST/api/pay/unifiedOrder
    Body request parameters
    {
  "amount": "20",
  "currency": "PKR",
  "customerContact": "03001234567",
  "customerEmail": "caizhuch1199w@gmail.com",
  "customerName": "GDW",
  "mchNo": "M1677225721",
  "mchOrderNo": "BJST73520250300058",
  "notifyUrl": "http://47.241.33.220:8896/tarspay/notify",
  "returnUrl": "https://47.241.33.220:8896/notify/return",
  "wayCode": "easypaisa"
}

    Request parameters#

    NameLocationTypeRequiredDescription
    X-API-KEYheaderstringYpublic key
    X-API-NONCEheaderstringYrequest time (timestamp, accurate to milliseconds)
    X-API-SIGNATUREheaderstringYsignature (refer to signature algorithm)
    mchNobodystringYmerchant number
    mchOrderNobodystringYmerchant order number (customized by merchant, cannot be repeated)
    wayCodebodystringYPayment method (easypaisa、jazzcash)
    amountbodystringYAmount (two decimal places. It cannot be zero and must meet the amount standard.)
    currencybodystringYcurrency(PKR)
    notifyUrlbodystringYnotification address
    Return to example
    {
    "code": 0,
    "data": {
        "amount": "20",
        "body": "Test",
        "countryCode": "pk",
        "currency": "PKR",
        "customerContact": "3001234567",
        "expiredTime": 1742282136,
        "mchOrderNo": "BJST648202503000207",
        "orderState": 1,
        "originalAccountNumber": "123456789",
        "payDataType": "payurl",
        "payOrderId": "P1901532855833436162",
        "payUrl": "https://checkout-s2.pk-bpay.com/pay-v2.php/630848dff40a0f72ce09e448084acdc954b441a3c04b2",
        "payWays": {
            "ewallet": [
                {
                    "countryCode": "pk",
                    "createdAt": 0,
                    "id": 114,
                    "payWay": "easypaisa",
                    "payWayLogo": "https://defipay.oss-ap-southeast-1.aliyuncs.com/easypaisa.png",
                    "payWayType": "ewallet",
                    "skipMode": 2,
                    "state": 1,
                    "updatedAt": 0
                }
            ]
        },
        "requestUrl": "https://www.tarspay.com/notify/return",
        "subject": "Buycar"
    },
    "msg": "SUCCESS",
    "sign": ""
}
"

    Return results#

    NameTypeDescription
    amountstringbill amount
    countryCodestringcountry code
    currencystringcurrency number
    customerContactstringuser contact information
    mchOrderNostringmerchant order number
    orderStateintegerorder status 0: order generated, 1: payment in progress, 2: payment successful, 3: payment failed, 6: timeout cancellation, 9: partial payment
    payOrderIdstringpayment order number
    payUrlstringCashier address
    payWaysarraypayment methods
    payment method:
    NameTypeDescription
    countryCodestringcountry code
    payWaystringpayment method code
    payWayLogostringpayment method logo
    payWayTypestringpayment method type
    #Pay on behalf of

    POST payment for unified order placement#

    POST HTTP_HOST/api/payOut/unifiedOrder
    Body request parameters
    {
  "amount": "50",
  "cnic": "00000000400000",
  "currency": "PKR",
  "customerAccountNumber": "03339605665",
  "customerContact": "03339605665",
  "customerEmail": "g762646676@126.com",
  "customerName": "ZEESHAN TAHIR",
  "mchNo": "M1677225721",
  "mchOrderNo": "BJST969202503000840",
  "notifyUrl": "http://47.241.33.220:8896/tarspay/notify",
  "wayCode": "jazzcash"
}

    Request parameters#

    NameLocationTypeRequiredDescription
    X-API-KEYheaderstringYpublic key
    X-API-NONCEheaderstringYrequest time (timestamp, accurate to milliseconds)
    X-API-SIGNATUREheaderstringYsignature (refer to signature algorithm)
    mchNobodystringYmerchant number
    mchOrderNobodystringYmerchant order number (customized by merchant, cannot be repeated)
    wayCodebodystringYPayment method (jazzcash、easypaisa)
    amountbodystringYamount (no decimals. It cannot be zero and must meet the amount standard.)
    currencybodystringYcurrency(PKR)
    notifyUrlbodystringYnotification address
    customerNamebodystringNusername
    customerContactbodystringYmobile phone number
    customerAccountNumberbodystringNuser bank card
    customerEmailbodystringNUser email
    cnicbodystringYID number
    {
  "code": 0,
  "data": {
    "mchOrderNo": "M1655535407",
    "payOrderId": "P1551409540398772225"
  },
  "msg": "SUCCESS",
  "sign": "3045022100c3998421fd646521777d0c736753704931f801331dec55f109258dd8a93083c402207c11e37d70477b30ad9e0c42072a3fb5af1a78809ca7f8023672451e62e8f69f"
}

    Return results#

    Note: When the code return is not 0, the data returned is null.
    NameTypeDescription
    mchOrderNostringmerchant order number (returned after successful request)
    payOrderIdstringplatform order number (returned after successful request)

    Collection order inquiry#

    POST to obtain collection order information#

    POST HTTP_HOST/api/payInInfo
    Body request parameters
    {
  "mchNo": "M1655535407",
  "mchOrderNo": "A1547429458697129178"
}

    Request parameters#

    NameLocationTypeRequiredDescription
    X-API-KEYheaderstringYpublic key
    X-API-NONCEheaderstringYrequest time (timestamp, accurate to milliseconds)
    X-API-SIGNATUREheaderstringYsignature (refer to signature algorithm)
    mchNobodystringYmerchant number
    payOrderIdbodystringNplatform order number (choose one of platform order number and merchant order number)
    mchOrderNobodystringNmerchant order number (choose one of platform order number and merchant order number)
    Return to example
    {
  "code": 0,
  "data": {
    "currency": "PKR",
    "fee": "0",
    "mchNo": "M1655535407",
    "mchOrderNo": "A1547429458697129178",
    "orderAmount": "100",
    "payAmount": "100",
    "payOrderId": "P1547429458697129178",
    "state": 2
  },
  "msg": "SUCCESS"
}

    Return results#

    NameTypeDescription
    payOrderIdstringpayment order number
    mchNostringmerchant number
    mchOrderNostringmerchant order number
    orderAmountstringoriginal transaction amount of bill
    payAmountstringpayment amount
    currencystringthree-digit currency code
    statestringpayment status: 0-Order generated, 1-Payment in progress, 2-Payment successful, 3-Payment failed, 4-Cancelled, 5-Refunded, 6-Order closed, 7-Queue, 8 -We reject, 9-Partial payment
    feestringmerchant fee

    Payment order inquiry#

    POST Get payment order information#

    POST HTTP_HOST/api/payOutInfo
    Body request parameters
    {
  "mchNo": "M1655535407",
  "mchOrderNo": "A1547429458697129178"
}

    Request parameters#

    NameLocationTypeRequiredDescription
    X-API-KEYheaderstringYpublic key
    X-API-NONCEheaderstringYrequest time (timestamp, accurate to milliseconds)
    X-API-SIGNATUREheaderstringYsignature (refer to signature algorithm)
    mchNobodystringYmerchant number
    payOrderIdbodystringNplatform order number (choose one of platform order number and merchant order number)
    mchOrderNobodystringNmerchant order number (choose one of platform order number and merchant order number)
    Return to example
    {
  "code": 0,
  "data": {
    "currency": "PKR",
    "fee": "0",
    "mchNo": "M1655535407",
    "mchOrderNo": "A1547429458697129178",
    "orderAmount": "100",
    "payAmount": "100",
    "payOrderId": "P1547429458697138178",
    "state": 2
  },
  "msg": "SUCCESS"
}

    Return results#

    NameTypeDescription
    payOrderIdstringpayment order number
    mchNostringmerchant number
    mchOrderNostringmerchant order number
    orderAmountstringoriginal transaction amount of bill
    payAmountstringpayment amount
    currencystringthree-digit currency code
    statestringpayment status: 0-order generated, 1-payment in progress, 2-payment successful, 3-payment failed, 8-rejected
    feestringmerchant fee

    Return results#

    NameTypeDescription
    statusintStatus, 0: Failure. 1: Success
    messagestring
    status information
    utrstringutr
    payOrderIdstringPlatform order number
    mchOrderNostringMerchant order number

    Merchant balance information query#

    POST to obtain merchant balance information#

    POST HTTP_HOST/api/balanceInfo
    Body request parameters
    {
    "mchNo": "M1655535407"
}

    Request parameters#

    NameLocationTypeRequiredDescription
    X-API-KEYheaderstringYpublic key
    X-API-NONCEheaderstringYrequest time (timestamp, accurate to milliseconds)
    X-API-SIGNATUREheaderstringYsignature (refer to signature algorithm)
    mchNobodystringYmerchant number
    Return to example
    {
    "code": 0,
    "data": {
        "availableAmount": "294876",
        "frozenAmount": "1986",
        "mchNo": "M1658240182"
    },
    "msg": "SUCCESS",
    "sign": "3045022100e659480ea76d87c26e0054bda5a788737d41f26d4dec365fba936028248785140220540c9bb2b9fe6fc928dc2ae4c531ee00a82615bc37b77b02 ca41cffeeaddc627"
}

    Return results#

    NameTypeDescription
    availableAmountstringavailable balance
    frozenAmountstringfrozen balance
    mchNostringmerchant number

    Callback notification#

    Submission method: POST#

    When receiving point-to-point communication from the server, the interface returns "OK" (without double quotes, OK is in capital letters), otherwise point-to-point notifications will be sent repeatedly (default 16 times).
    OK

    Content-Type#

    application/json

    Verify signature#

    Use the Tarspay public key to verify the signature of [return data](#return description).

    Request parameters#

    NameTypeRequiredDescription
    bizTypenumberYbusiness type: 1-Collection 2-Payment
    payOrderIdstringYpayment order number
    mchNostringYmerchant number
    mchOrderNostringYmerchant order number (customized by merchant, cannot be repeated)
    orderAmountstringYoriginal transaction amount of bill
    payAmountstringYpayment amount
    currencystringYthree-digit currency code
    statenumberYpayment status: 2-payment successful, 3-payment failed, 9-partial payment (collection)
    feestringYmerchant fee
    failReasonstringNfailure reason
    Callback signature verification description: X-RESP-SIGNATURE request header carries signature
    Signature rules: After JSONizing the request parameters, put the obtained signature in the header, and obtain the signature directly from the response header. To verify the signature, use verifyEcdsaSignature() in the ECSDAKit tool class below.
    Example:
    OrderNotifyDTO.class

    Signature tool class#

    Maven dependencies#

    <dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bcprov-jdk15on</artifactId>
    <version>1.64</version>
    <scope>compile</scope>
</dependency>

    ECSDAKit#

    Utils#

    java demo#

    php demo#

    Download link

    Error coding table#

    Error codeError description
    -1System error
    5003001Missing parameter
    5003002Merchant or APIKey does not exist
    5003003Merchant disabled
    5003004Merchant not certified
    5003005Merchant api key does not exist
    5003005Merchant or api key does not exist
    5003006api key expired
    5003007ip error
    5003008Signature error
    5003009Payment method not supported
    5003010Order status error
    5003011Merchant order number already exists
    5003012URL format error
    5003013Channel error
    5003014Merchant rate configuration is not initialized
    5003015Channel does not exist
    5003017Failed to create collection order
    5003018Failed to check collection order
    5003010Failed to create payment order
    5003020Failed to query payment
    5004006Insufficient merchant balance
    500321Amount format is incorrect
    500322URL not supported
    500323Remote client error
    500324Order expired
    500326Error in querying channel balance
    500327Wrong payment method
    修改于 2025-03-17 08:27:12
    上一页
    Bengal🇧🇩
    Built with