/v1/payments/pay

POST /v1/payments/pay

The pay API is used to initiate a payment at wallet.

Note: A payment which takes place at wallet.

1)merchant/partner initiates payment request to wallet through Payment Interface.

2)Wallet will handle different payment scenarios base on the parameters in request.

Currently, payment API support following acquiring scenarios:

  • Cashier Payment:Usually used in online payment scenario. In this scenario, merchant/partner will call this payment API to create order, and wallet will return cashier page url to merchant/partner, and then redirect to this cashier page. So user can finished payment in cashier page.

Message structure

Request

Property

Data type

Required

Description

partnerId

String 

Yes

The partnerId allocated by wallet.

Max. length: 32 characters.

appId

String 

No

The mini program ID.

Max. length: 32 characters.

productCode

String 

No

Defined by wallet, wallet will use productCode to get the contract config which include fee,limit info.

Max. length: 32 characters.

paymentOrderTitle

String 

Yes

The order title of this payment.

Max. length: 256 characters.

paymentRequestId

String 

Yes

The unique ID of a payment generated by merchant.

  • Max. length: 64 characters.
  • This field is used for the idempotence control. For the payment requests which are initiated with the same paymentRequestId and reach a final status (S or F),  the wallet must return the unique result.

paymentAmount

Amount

Yes

Order amount for display of user consumption records, payment results page.

paymentMethods

PaymentMethod

No

The paymentMethod used to collect fund by wallet.

paymentAuthCode

String 

No

If payFactor.isAgreementPay is true,then it's the accessToken of wallet user, if payFactor.isPaymentCode is true, then it's the authcode of wallet user.

Max. length: 128 characters.

paymentFactor

PaymentFactor

No

In the Mini Program scenario, it is fixed value, map format, {"isCashierPayment" : true}.

paymentExpiryTime

String/Datetime

No

The payment order close time defined by merchant, which follows the ISO 8601 standard.

paymentReturnUrl

String 

No

The redirect url defined by merchan.

Max. length: 1024 characters.

paymentNotifyUrl

String 

No

The payment success notify url defined by merchant.

Max. length: 1024 characters.

mcc

String 

No

The merchant category code.

Max. length: 32 characters.

extraParams

Map

No

Map format, specific payment ability which provided by wallet, now we only support 1 key : ORDER.

extendInfo

String 

No

The extend information,wallet and merchant can put extend info here.

Max. length: 4096 characters.

envInfo

EnvInfo

No

Environment information of mobile phone.

Response

Property

Data type

Required

Description

result

Result

Yes

The request result, which contains information related to the request result, such as status and error codes.

paymentId

String 

No

The unique ID of a payment generated by Wallet.

Max. length: 64 characters.

paymentTime

String/Datetime

No

Payment success time, which follows the ISO 8601 standard.

actionForm

ActionForm

No

authExpiryTime

String/Datetime

No

Authorization expiry time, has value only when paymentFactor.isAuthorizationPayment is true.

extendInfo

String 

No

The extend information,wallet and merchant can put extend info here.

Max. length: 4096 characters.

Result process logic

For different request results, different actions are to be performed. See the following list for details:

  • result.resultStatus = S
    • That means this transaction is success, merchant/partner can update transaction to success. What need to notice is :
      • In payment evaluation scenario, 'S' just means evaluate success, no real fund transfer.  
      • In authorization payment scenario, 'S' just means authorization success, need wait for capture operation to finish the  transaction(finish final fund flow).
  • result.resultStatus = A
    • That means transaction already accept by wallet. Merchant/partner need continue the next step operation according to actionForm response.  Such as display order code to user or redirect to wallet cashier page.
  • result.resultStatus = F
    • That means this transaction is failed, the failed reason can refer to result code param.  Usually F transactions can not be success again if use the same payment request to call wallet.
  • result.resultStatus = U
    • That means unknown exception occur on wallet side. Merchant/partner can inquiry payment result or waiting for payment status notification to get the real payment result. What need to notice is :
      • Payment evaluation scenario can not inquiry.
      • U status can not set to fail or success on merchant/partner system.
      • U status can not refund to user by offline(Maybe will make fund loss).

Result

resultStatus

resultCode

resultMessage

S

SUCCESS

Success.

U

UNKNOWN_EXCEPTION

An API calling is failed, which is caused by unknown reasons.

U

REQUEST_TRAFFIC_EXCEED_LIMIT

The request traffic exceeds the limit.

U

PAYMENT_IN_PROCESS

The payment is still under process.

A

ACCEPT

Need next action according to actionForm.

F

REPEAT_REQ_INCONSISTENT

Repeated submit, and requests are inconsistent.

F

PROCESS_FAIL

A general business failure occurred. Don't retry.

F

INVALID_API

The called API is invalid or not active.

F

PARAM_ILLEGAL

Illegal parameters exist. For example, a non-numeric input, or an invalid date.

F

ACCESS_DENIED

The access is denied.

F

PAYMENT_AMOUNT_EXCEED_LIMIT

Payment amount exceeds limit.

F

USER_NOT_EXIST

User not exist.

F

USER_STATUS_ABNORMAL

The user status is abnormal.

F

USER_BALANCE_NOT_ENOUGH

User balance is not enough for this payment.

F

PARTNER_NOT_EXIST

Partner not exist.

F

PARTNER_STATUS_ABNORMAL

Partner status abnormal.

F

RISK_REJECT

Risk reject.

F

CURRENCY_NOT_SUPPORT

The currency is not supported.

F

ORDER_STATUS_INVALID

Order is in invalid status such closed.

F

INVALID_ACCESS_TOKEN

Invalid accesstoken.

F

USER_AMOUNT_EXCEED_LIMIT

Payment amount exceeds user's amount limit.

F

EXPIRED_ACCESS_TOKEN

The access token is expired.

F

AUTH_CODE_ALREADY_USED

Auth code already used.

F

INVALID_CODE

Auth code illegal.

F

EXPIRED_AGENT_TOKEN

The access token of mini program is expired.

F

INVALID_AGENT_TOKEN

The access token of mini program is invalid.

Sample

Cashier Payment

For example, a user purchases a 100 USD merchandise at the merchant/partner(online merchant usually) , merchant/partner call this payment api to create payment order first, wallet will return payment order id and wallet cashier page url to merchant/partner, then merchant/partner can redirect user to wallet cashier page with my.tradePay api.

/v1/payments/pay
  1. Firstly the Mini Program create order (Step 1).
  2. The merchant server calls /v1/payments/pay interface with paymentNotifyUrl to initiate payment flow (Step 2).
  3. E-wallet server returns payment detail information with paymentId to the merchant server (Step 3).
  4. The merchant server has to pass through the payment detail information to the Mini Program (step 4).
  5. And the Mini Program should call my.tradePay interface to do payment (Step 5).
  6. When the payment reaches the final status, e-wallet server notifies the payment result to the merchant server with paymentNotifyUrl provided in Step 2 (Step 8).
  7. Also E-wallet App returns payment result to the Mini Program (Step 9).

Request

copy
{
    "partnerId": "P000000000000001xxxx",
    "paymentRequestId": "2019112719074101000700000077771xxxx",
    "paymentOrderTitle": "SHOES",
    "productCode": "PC_5800000001",
    "mcc": "4399",
    "paymentAmount": {
        "currency": "USD",
        "value": "10000"
    },
    "paymentFactor": {
        "isCashierPayment": true
    },
    "paymentReturnUrl":"https://www.merchant.com/redirectxxx",
    "paymentNotifyUrl":"https://www.merchant.com/paymentNotifyxxx",
    "extraParams": {
        "ORDER": "{\"referenceOrderId\":\"ID_000001\",\"orderAmount\":\"{\\\"currency\\\":\\\"USD\\\",\\\"value\\\":\\\"10000\\\"}\"}"
    },
    "extendInfo": "{\"customerBelongsTo\":\"siteNameExample\"}", 
    "envInfo": {
        "osType": "IOS",
        "terminalType": "APP"
    }
}
  • partnerId is the identifier of a merchant/partner, allocated by Wallet.
  • paymentRequestId is generated by merchant/partner, uniquely identifies the payment. Wallet must make use of paymentRequestId and partnerId for idempotent control. For example, if a payment with paymentRequestId== 2019112719074101000700000077771xxxx and partnerId==P000000000000001xxxx  has been processed successfully by Wallet, when merchant/partner uses the same paymentRequestId  and partnerId for payment, Wallet will respond with successful payment.
  • productCode defined by wallet, wallet will use productCode to get the contract config which include fee,limit info.
  • paymentFactor In the Mini Program scenario, the PaymentFactor only have the fixed value: isCashierPayment = true
  • paymentReturnUrl is the url defined by merchant/partner.  In cashier payment scenario, after user finished payment in wallet cashier page, wallet will direct back to merchant base on this URL.
  • paymentNotifyUrl is the url defined by merchant/partner.  In cashier payment scenario, after user finished payment in wallet cashier page, wallet will notify merchant the payment result base on this URL.
  • paymentAmount describes the amount of 100 USD to be collected by Wallet from user account for this payment.
  • extraParams, only includes 1 key - ORDER now.  ORDER describes the order details of the purchase of the 100 USD merchandise by the  user at the  merchant. Such as Merchant, Buyer, Goods, etc are included in order . The information in the Order is only used to  display user's payment result page and transactions history,  regulation reporting, etc. It will not make use of the amount in the order for fund operation.
  • extendInfo, includes key - customerBelongsTo the e-wallet that the customer uses. Corresponding to the field 'siteName' that obtained from the API 'my.getSiteInfo', in the Mini Program scenario this is mandatory.

Response

copy
{
 "result": {
    "resultCode":"ACCEPT",
    "resultStatus":"A",
    "resultMessage":"accept"
 },
 "paymentId": "string",
 "actionForm":{
    "actionFormType":"REDIRECTION",
    "redirectionUrl":"http://www.merchant.com/cashier?orderId=xxxxxxx"
 }
}
  • result.resultStatus ==A shows that the  payment is accept success. After user finish payment in cashier page, payment will change to success.
  • paymentId is generated by Wallet, uniquely identifies the payment.
  • actionForm will return cashier  page url to merchant/partner,  after merchant/partner received accept result, will redirect to this URL.