API access documentation
All server-side interface calls need to be encoded and signed as required. For details, please refer to API Interface Signature Verification
Payment
Interface Description
Receipt is the entry point for merchants to initiate collection business scenarios. The merchant server initiates a payment request to Paynicorn. Paynicorn will encapsulate the list of payment methods according to the parameters, and return the link to the cashier or initiate payment directly.
interface address
https://api.paynicorn.com/trade/v3/transaction/pay
request parameters
Field filling requirements, M: mandatory, O: optional
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| amount | String(32) | M | The smallest unit of local currency, with two decimal places, see Appendix Country Currency Comparison Table |
| countryCode | String(2) | M | Country Code, see Appendix Country Currency Comparison Table |
| orderId | String(64) | M | Merchant order number |
| orderDescription | String(1024) | M | order description |
| currency | String(3) | M | Currency Code (CurrencyCode), see Appendix Country Currency Comparison Table |
| payMethod | String(64) | O | Payment method code, if specified, use the payment method, do not enter the paynicorn cashier, if not specify, enter the paynicorn cashier to select the payment method, see appendix [payment method list](/docs/appendix/ payment-method) |
| language | String(8) | O | Default cashier language |
| cpFrontPage | String(1024) | O | The address of the payment result page accepted by the front-end, if provided, the page will be automatically redirected to this address after the payment is completed |
| palmAuthCode | String(8) | O | Through PalmID authorization and authentication, it provides authorized payment function. (Required: 1. Integrate PalmID, 2. Contact Paynicorn operators to activate authorized payment permissions) |
| String(128) | O | User mailbox, if provided, the channel that needs to use the user's mailbox will directly use the provided mailbox, skip the page where the user fills in the mailbox | |
| phone | String(32) | O | User's mobile phone number (excluding country code), if provided, the channel that needs to use the user's mobile phone number will directly use the provided mobile phone number, skip the page where the user fills in the mobile phone number |
| payByLocalCurrency | Boolean | O | Whether to pay in local currency, the default is false, when it is true and the currency is not the local currency of countryCode, it will try to convert non-local currency to local currency for payment |
| memo | String(1024) | O | Extended information (stores JSON string) |
Response parameters
| parameter name | type | remarks |
|---|---|---|
| code | String(16) | For status codes, see Status Code |
| message | String(256) | Message see Status Code |
| txnId | String(64) | Transaction number |
| status | String(2) | Order status (1: successful; -1: processing; 0: failed) |
| webUrl | String(64) | H5 payment address |
For the payment interface, you can specify the payment method used for this payment by passing in payMethod, skipping the payment method page at the Paynicorn checkout counter
If the payment method requires the user's mobile phone number, you can pass in the mobile phone number through the phone, skipping the mobile phone number input page at the Paynicorn checkout counter
By providing the corresponding parameters, you can skip the Web page of the Paynicorn cashier and initiate the corresponding payment directly. In this case, the webUrl in the Paynicorn response parameter is empty, and the merchant can implement the relevant front-end page by itself
For the specific supported payment methods and the parameters that need to be passed in related methods, please refer to List of Payment Methods
Refund
Interface Description
For a successful payment order, initiate a refund application, synchronously accept, asynchronously process, and call back the result
interface address
https://api.paynicorn.com/trade/v3/transaction/refund
interface parameters
Field filling requirements M:mandatory ，O:optional
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| payTxnId | String(64) | M | Original transaction number |
| refundId | String(64) | M | Merchant refund order number |
Response parameters
| Parameter Name | Type | Required | Remarks |
|---|---|---|---|
| code | String(16) | M | Status code see Status Code |
| message | String(256) | M | Message see status-code |
| txnId | String(64) | M | Transaction ID |
| status | String(2) | M | Order status (1: success; -1: processing; 0: failure) |
Payout
Interface Description
The payment interface is not enabled by default. It needs to be enabled. Contact kailan.ruan@transsion.com
interface address
https://api.paynicorn.com/trade/v3/transaction/payout
interface parameters
Field filling requirements M: mandatory, O: optional
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| orderId | String(64) | M | Merchant payment order number |
| currency | String(3) | M | Currency Code (CurrencyCode), see Appendix Country and Currency Comparison Table |
| amount | String(32) | M | amount |
| countryCode | String(2) | M | Country Code, see Appendix Country and Currency Comparison Table |
| payoutMethod | String(64) | M | Transfer type (CARD,MTN,MPESA,PAYNICORNPAY,AIRTEL...) |
| name | String(64) | M | Payee name |
| account | String(64) | M | Receiving account |
| bankCode | String(64) | O | Bank code (required when transfer type is bank card) see appendix Bank Code |
Response parameters
| Parameter Name | Type | Required | Remarks |
|---|---|---|---|
| code | String(16) | M | Status code see Status Code |
| message | String(256) | M | Message see status-code |
| status | String(2) | M | Order status (-1: processing; 0: failed) |
| txnId | String(64) | O | Transaction ID |
Payout2
Interface Description
The implementation will issue funds to the user, and the merchant can call this interface to implement, and transfer the funds from the merchant's own payout account to the paynicorn app user
interface address
https://api.paynicorn.com/trade/customer/oauth/transaction/payout
interface parameters
Field filling requirements M: mandatory, O: optional
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| orderId | String(64) | M | Merchant payment order number |
| currency | String(3) | M | Currency Code (CurrencyCode), see Appendix Country and Currency Comparison Table |
| amount | String(32) | M | amount |
| countryCode | String(2) | M | Country Code, see Appendix Country and Currency Comparison Table |
| name | String(64) | M | Payee name |
| openId | String(64) | M | OpenId |
Response parameters
| Parameter Name | Type | Required | Remarks |
|---|---|---|---|
| code | String(16) | M | Status code see Status Code |
| message | String(256) | M | Message see status-code |
| status | String(2) | M | Order status (-1: processing; 0: failed) |
| txnId | String(64) | O | Transaction ID |
Query transaction result interface (Query)
Interface Description
Used for query of asynchronous interface and synchronous interface timeout scenario
interface address
https://api.paynicorn.com/trade/v3/transaction/query
request parameters
Field filling requirements M:mandatory ，O:optional
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| orderId | String(64) | M | Merchant order number |
| txnType | String(8) | M | Transaction Type |
Please refer to appendix transaction type for transaction type
Response parameters
| Parameter Name | Type | Required | Remarks |
|---|---|---|---|
| code | String(16) | M | Status code see Status Code |
| message | String(256) | M | Message see status-code |
| txnId | String(64) | M | Transaction ID |
| status | String(4) | M | Payment result |
| completeTime | String(16) | O | Transaction processing completion time |
Asynchronous notification interface (Postback)
Interface Description
Asynchronous transaction result notification, if the transaction result cannot be obtained immediately for payment collection and authorized payment, when the transaction status changes, paynicorn will call the asynchronous notification result set by the merchant to notify the merchant server of the latest order status.
interface address
Provided by the merchant, configured through the merchant platform, see Set callback address
request parameters
| Parameter Name | Type | Required | Remarks |
|---|---|---|---|
| txnId | String(64) | M | Payment order number |
| orderId | String(64) | M | Merchant's order number |
| amount | String(32) | M | amount |
| currency | String(3) | M | Currency |
| countryCode | String(2) | M | country code |
| status | String(4) | M | Payment status |
| code | String(6) | M | Status code |
| message | String(256) | M | message |
| memo | String(1024) | O | Remarks |
Response parameters
After the merchant receives the callback notification, it needs to respond according to the requirements of Paynicorn
HttpsStatus=200 means that the notification is received and the string success_{txnId} is returned, other means the notification failed
If success_{txnId} is not returned, it will continue to notify until it succeeds, up to 7 times. The notification interval is incremented by 10*2^(n-1) (unit: minute, n represents the number of notifications), and the frequency is: 10min, 20min, 40min, 80min, 160min,320min
Get the payment method (PayMethod)
Interface Description
Get available payment methods
interface address
https://api.paynicorn.com/trade/v3/transaction/method
request parameters
Field filling requirements M:mandatory ，O:optional
| Parameter name | Type | Fill in requirements | Description |
|---|---|---|---|
| countryCode | String(2) | M | Country Code, see Appendix Country and Currency Comparison Table |
| currency | String(3) | M | Currency Code (CurrencyCode), see Appendix Country and Currency Comparison Table |
| txnType | String(8) | M | transaction type, see appendix transaction-type |
Response parameters
| Parameter Name | Type | Required | Remarks |
|---|---|---|---|
| code | String(16) | M | Status code see Status Code |
| message | String(256) | M | Message see status-code |
| methodInfo | Array<MethodInfo> | O | List of available payment methods |
MethodInfo
| Parameter Name | Type | Required | Remarks |
|---|---|---|---|
| code | String(32) | M | Payment method code |
| name | String(32) | M | Payment method name |
| icon | String(128) | M | Payment method icon URL |
| methodType | String(16) | M | Payment method type |
| supportAmount | Array<Decimal> | O | Support amount, discrete value, and minAmount\maxAmount will not appear at the same time |
| minAmount | Decimal | O | Support the minimum amount, will not appear at the same time as supportAmount |
| maxAmount | Decimal | O | Support the maximum amount, will not appear at the same time as supportAmount |
| discount | Decimal | O | Discount |