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

    Brazil🇧🇷

    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.pro

    HTTP_METHOD#

    GET, POST need to be capitalized

    HTTP_REQUEST_PATH#

    The PATH part of the request URL, for example: https://payment.tarspay.pro/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.pro/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 LarkPay 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": "100",
  "body": "your productinfo",
  "currency": "BRA",
  "mchNo": "80002",
  "mchOrderNo": "M202207131958",
  "notifyUrl": "https://www.yourcompany.com/notify",
  "returnUrl": "https://www.yourcompany.com/return",
  "subject": "your subject",
  "wayCode": "CASHIER"
}

    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)
    wayCodebodystringY- Cashier: CASHIER (use the cashier of this system) - Non-cashier: PIX
    amountbodystringYthe amount
    currencybodystringYcurrency（BRA）
    subjectbodystringYproduct title
    bodybodystringYproduct Description Information
    notifyUrlbodystringYnotification address
    returnUrlbodystringYreturn address
    customerNamebodystringNusername
    customerEmailbodystringNuser Email
    customerContactbodystringNuser phone
    Return to example
    {
  "code": 0,
  "data": {
    "amount": "5000",
    "body": "your productinfo",
    "countryCode": "br",
    "currency": "BRA",
    "customerContact": "15221113201",
    "mchOrderNo": "202207161603q01",
    "orderState": 0,
    "payOrderId": "P1551396771600912385",
    "payUrl": "https://example.com/larkpayToC/#/order/id/P1551396771600912385",
    "reference": "00020101021226860014br.gov.bcb.pix2564qrcode.fitbank.com.br/QR/cob/74E84A5EA90F79A16AEAAC1D9B73E89BB215204000053039865802BR5925ONEPAY MEIOS DE PAGAMENTO6009Fortaleza610960731-30562070503***6304A7AE",
    "payWays": {
      "PIX": [
        {
          "countryCode": "br",
          "payWay": "PIX",
          "payWayLogo": "https://example.com/larkpay_v_1.0/PERMATA.png",
          "payWayType": "PIX"
        }
      ]
    },
    "subject": "your subject"
  },
  "msg": "SUCCESS",
  "sign": "3045022100f32d38d4457295f0ce70376845458ec55a9fad34cce39ae11cd0cdbadd90639e02207d23e33f9b95944fb32923707c30b913063b082995b7e5fb9d8d2369f1ab4e53"
}

    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
    payUrlstringpay Url
    referencestringMerchants can generate their own QR code based on this value and return it through non cash register methods
    payWaysarraypayWays
    payment method:
    NameTypeDescription
    countryCodestringCountry code
    payWaystringPayment method code (refer to [Payment method code](#Payment method code))
    payWayLogostringPayment method logo
    payWayTypestringPayment method type
    #Pay on behalf of

    Payment code#

    Payment bank code#

    Bank & e-wallet codeBank & e-wallet name
    PIX_CPFPIX_CPF
    PIX_CNPJPIX_CNPJ
    PIX_PHONEPIX_PHONE
    PIX_EMAILPIX_EMAIL
    PIX_EVPPIX_EVP

    POST payment for unified order placement#

    POST HTTP_HOST/api/payOut/unifiedOrder
    Body request parameters
    {
  "amount": "40",
  "customerAccountNumber": "10002523675",
  "currency": " BRA",
  "mchNo": "80001",
  "mchOrderNo": "2022071201011",
  "notifyUrl": "http://www.yourcompany.com/notify",
  "wayCode": "PIX",
  "accountTax": "459920019932",
  "bankName": "PIX_CPF"
}

    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)
    wayCodebodystringYPIX
    amountbodystringYthe amount
    currencybodystringYcurrency(BRA)
    notifyUrlbodystringYnotification address
    customerNamebodystringYusername
    customerContactbodystringYMobile phone number
    customerAccountNumberbodystringYuser accountNumber +55{10-11digit number}
    customerEmailbodystringYuser email
    accountTaxbodystringYduty paragraph，The individual entity is CPF, and the company entity is CNPJ
    bankNamebodystringYpayment code (refer to [payment code](#payment code))
    {
  "code": 0,
  "data": {
    "mchOrderNo": "M1655535407",
    "payOrderId": "P1551409540398772225"
  },
  "msg": "SUCCESS",
  "sign": "3045022100c3998421fd646521777d0c736753704931f801331dec55f109258dd8a93083c402207c11e37d70477b30ad9e0c42072a3fb5af1a78809ca7f 8023672451e62e8f69f"
}

    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": "lin1231241241414"
}

    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": "BRA",
    "fee": "0",
    "mchNo": "M1655535407",
    "mchOrderNo": "",
    "orderAmount": "10000",
    "payAmount": "10000",
    "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": "lin1231241241414"
}

    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": "BRA",
    "fee": "0",
    "mchNo": "M1655535407",
    "mchOrderNo": "",
    "orderAmount": "10000",
    "payAmount": "10000",
    "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

    Transaction history#

    POST Get transaction history (final data-success/failure)#

    POST HTTP_HOST/api/transInfo
    Body request parameters
    {
  "mchNo": "M1658240182",
  "bizType": 1,
  "startTime": 1656604800,
  "endTime": 1667145600,
  "pageNumber": 1,
  "pageSize": 20
}

    Request parameters#

    NameLocationTypeRequiredDescription
    X-API-KEYheaderstringYpublic key
    X-API-NONCEheaderstringYRequest time (timestamp, accurate to milliseconds)
    X-API-SIGNATUREheaderstringYsignature (refer to signature algorithm)
    mchNobodystringYmerchant number
    bizTypebodynumberNBusiness type: 1-Collection on behalf of others 2-Payment on behalf of others 3-USDT withdrawal 4-Withdrawal
    startTimebodynumberNStart time (server 0 time zone timestamp, accurate to seconds)
    endTimebodynumberNEnd time (server 0 time zone timestamp, accurate to seconds)
    pageNumberbodynumberYpage number
    pageSizebodynumberYpage size (max 50)
    Return to example
    {
   {
    "code": 0,
    "data": {
        "current": 1,
        "hitCount": false,
        "optimizeCountSql": true,
        "orders": [],
        "pages": 1,
        "records": [{
                "address": "",
                "amount": "30880",
                "bankCard": "123456789",
                "bankCode": "",
                "bankName": "",
                "bizType": 1,
                "body": "Test",
                "createdAt": 1658714327,
                "currency": "BRA",
                "email": "g762646676@126.com",
                "mchFeeAmount": "1120",
                "mchName": "DW",
                "mchNo": "M1658240182",
                "mchOrderNo": "YN20220725000003",
                "mobilePhone": "13116709877",
                "orderAmount": "32000",
                "payOrderId": "P1551386450310656001",
                "payWay": "PIX",
                "payerName": "DW",
                "state": 2,
                "subject": "buycar",
                "successTime": 1658715821
            },
            {
                "address": "",
                "amount": "27830",
                "bankCard": "",
                "bankCode": "",
                "bankName": "",
                "bizType": 1,
                "body": "buy",
                "createdAt": 1658714433,
                "currency": "BRA",
                "email": "g762646676@126.com",
                "mchFeeAmount": "6170",
                "mchName": "DW",
                "mchNo": "M1658240182",
                "mchOrderNo": "M1551386893266952193",
                "mobilePhone": "816153100",
                "orderAmount": "34000",
                "payOrderId": "P1551386893275340801",
                "payWay": "PIX",
                "payerName": "xxxx",
                "state": 2,
                "subject": "buy",
                "successTime": 1658717145
            },{
                "address": "",
                "amount": "27830",
                "bankCard": "",
                "bankCode": "",
                "bankName": "",
                "bizType": 1,
                "body": "buy",
                "createdAt": 1658714433,
                "currency": "BRA",
                "email": "g762646676@126.com",
                "mchFeeAmount": "6170",
                "mchName": "DW",
                "mchNo": "M1658240182",
                "mchOrderNo": "M1551386893266952193",
                "mobilePhone": "816153100",
                "orderAmount": "34000",
                "payOrderId": "P1551386893275340801",
                "payWay": "PIX",
                "payerName": "xxxx",
                "state": 2,
                "subject": "buy",
                "successTime": 1658717145
            }],
        "searchCount": true,
        "size": 20,
        "total": 2
    },
    "msg": "SUCCESS",
    "sign": "3045022100e659480ea76d87c26e0054bda5a788737d41f26d4dec365fba936028248785140220540c9bb2b9fe6fc928dc2ae4c531ee00a82615bc37b77b02ca41cffeeaddc627"
}

    Return results#

    NameTypeDescription
    amountstringSettlement quantity (when collection is made, it is the upper-point quantity (handling fee is deducted), when payment/withdrawal is made, it is the bill quantity (handling fee is not deducted))
    bankCardstringBank card number
    bankNamestringBank name
    bizTypenumberBusiness type: 1-Collection on behalf of others 2-Payment on behalf of others 3-USDT withdrawal 4-Withdrawal
    createdAtnumberOrder creation time (0 time zone timestamp, accurate to seconds)
    currencystringCurrency
    mchFeeAmountstringhandling fee
    mchNamestringMerchant name
    mchNostringMerchant number
    mchOrderNostringMerchant order number
    mobilePhonestringMobile phone number
    orderAmountstringOrder amount
    payOrderIdstringPayment serial number
    payWaystringPayment method name
    payWayTypestringPayment method
    payerNamestringUser name
    statenumberOrder status: 2-successful 3-failed 8-(payment) rejected 9-partial payment (payment amount is less than the order amount)
    successTimenumberis

    MERCHANT BALANCE INFOMATION 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 LarkPay 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
    上一页
    Philippines🇵🇭
    下一页
    Mexican🇲🇽
    Built with