Cashy Docs Center

Create Payin Order

API EndPoint

POST baseUrl + /api/payIn

Request Parameters

Parameter	Required	Type	Description	Example
`currency`	`Y`	`string(32)`	Currency code(`PKR`)	`PKR`
`payType`	`Y`	`int`	pls refer to Payin PayType Enum	36
`amount`	`Y`	`decimal(20,2)`	Amount	[100.00,50000.00]
`reusableStatus`	`Y`	`boolean`	Currently it can only be false	false
`mchOrderNo`	`Y`	`string(32)`	Merchant order number (should be unique in the merchant system)	order000000001
`expireTime`	`Y`	`long`	Expiration time, default 3600 seconds	3600
`notifyUrl`	`Y`	`string(250)`	webhooks (callback) address	`https://merchant.com/webhooks`
`nonceStr`	`Y`	`string(32)`	Random string	1863484722378907648
`remark`	`Y`	`string(32)`	Order remarks	remark
`realName`	`Y`	`string(32)`	Payer Name	Jack
`phone`	`Y`	`string(32)`	Payer phone number	3001234567
`email`	`Y`	`string(32)`	Payer email	`example@maildomain.com`
`idCard`	`Y`	`string(32)`	Payer ID number	1712041511
`idType`	`N`	`string(32)`	Payin Payer ID Type

Request Example

bash

curl -L 'baseUrl/api/payIn' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"nonceStr":"test001","currency":"PKR","payType":36,"amount":"100.0","reusableStatus":false,"mchOrderNo":"order000000001","expireTime":36000,"notifyUrl":"https://test.com/payment/cashy/payIn/callback","remark":"PayIn","realName":"test","phone":"3001234567","email":"test@gmail.com","idCard":"3310401123456"}'

Response Parameters

Parameter	Type	Description
`merchantId`	`long`	MerchantId
`mchOrderNo`	`string(32)`	Merchant order number
`orderNo`	`string(32)`	Platform order number
`amount`	`decimal(20,2)`	Amount
`orderFee`	`decimal(20,2)`	fee
`payCode`	`string(32)`	Payment account VA
`payUrl`	`string(250)`	Payment Url

Response Example

SuccessSome Error

json

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "1002001",
    "mchOrderNo": "order000000001",
    "orderNo": "PAYINxxxxxxxxx00000000001",
    "payCode": "646012000000015942",
    "payUrl": null,
    "payDeskUrl": "https://xxx.com/pay/PAYIN8232154612109344768",
    "amount": 100
  }
}

json

{
  "msg": "Payin_Order_Error",
  "code": 500
}

Query Payin Order

API EndPoint

POST baseUrl + /api/payInQuery

Request Parameters

Parameter	Required	Type	Example	Description
`mchOrderNo`	`N`	`string(32)`	1386556575370063873	Merchant order number
`orderNo`	`N`	`string(32)`	PAYIN8551843837024997376	Platform order number
`nonceStr`	`Y`	`string(32)`	9459931608	Random string

TIP

We recommend using orderNo (platform order number) first. At least one of the platform order number and the merchant order number must be passed.

Request Example

bash

curl -L 'baseUrl/api/payInQuery' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"mchOrderNo":"1386556575370063873","nonceStr":"9459931608","orderNo":"PAYIN8551843837024997376"}'

Response Parameters

Parameter	Type	Description
`merchantId`	`int`	Merchant id
`mchOrderNo`	`string(32)`	Merchant order number
`orderNo`	`string(32)`	Platform order number
`channelOrderNo`	`string(32)`	Channel order number
`payType`	`string(32)`	Payin PayType Enum
`payCode`	`string(32)`	Payment Code
`payUrl`	`string(250)`	Payment url
`amount`	`decimal(20,0)`	Amount
`fee`	`decimal(20,4)`	Fee
`orderStatus`	`string(32)`	Order StatusPayin Order Status Enum
`completionTime`	`yyyy-MM-dd HH:mm:ss`	Complete time

Response Example

SuccessPayment in progress

json

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "1002001",
    "mchOrderNo": "1386556575370063873",
    "orderNo": "PAYIN8551843837024997376",
    "payType": "43",
    "payCode": "",
    "payUrl": "https://m.dana.id/link/pay?bizNo=202412021112128001101660361270",
    "payDeskUrl": "https://idpaydesk2.brcashypro.com/views/pay.html?PAYIN8551843837024997376",
    "amount": "20000",
    "fee": "1700",
    "orderStatus": "SUCCESS",
    "completionTime": "2024-12-02 15:40:50",
    "nonceStr": null
  }
}

json

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "1002001",
    "mchOrderNo": "1386556575370063873",
    "orderNo": "PAYIN8551843837024997376",
    "payType": "43",
    "payCode": "",
    "payUrl": "https://m.dana.id/link/pay?bizNo=202412021112128001101660361270",
    "payDeskUrl": "https://idpaydesk2.brcashypro.com/views/pay.html?PAYIN8551843837024997376",
    "amount": "20000",
    "fee": "1700",
    "orderStatus": "PAYING",
    "completionTime": null,
    "nonceStr": null
  }
}

Supplementary instructions when orderType is PATCH

If the user does not pay according to the order amount or pays repeatedly, a supplementary order will appear. In this case, the orderType of the supplementary order is PATCH:

orderNo is the platform order number newly generated for this order.
patchOrderNo is the platform order number of the associated original order,
patchMchOrderNo is the merchant order number of the associated original order.
mchOrderNo is the merchant order number of the associated original order (with a serial number identifier). Note that at this time, the serial number identifier will be added to the end of the mchOrderNo returned by the callback to distinguish multiple partial repayment orders.

For example, if your merchant order number is MCH20230088, when the first partial payment is generated, we will add the serial number 00001 to the end of the merchant order number mchOrderNo of the original order.

The mchOrderNo you receive in the callback is MCH2023008800001, and so on.

When a patch order occurs, our robot will also notify the corresponding merchant group, and the notification will contain all the information you need.

When the orderType of the order is API:

patchOrderNo is the same as orderNo
patchMchOrderNo is the same as mchOrderNo

At this time, the above parameters have no additional meaning.

Async Webhook Notification

The webhooks url is provided by the merchant

POST Merchant NotifyUrl

Webhook Request Parameters

Parameter	Type	Description
`merchantId`	`int`	Merchant id
`mchOrderNo`	`string(32)`	Merchant order number
`orderNo`	`string(32)`	Platform order number
`amount`	`decimal(20,2)`	Amount
`fee`	`decimal(20,4)`	Fee
`payUrl`	`string(32)`	Payment url
`payDeskUrl`	`string(250)`	Paydesk url
`payType`	`string(32)`	Payin PayType Enum
`orderStatus`	`string(32)`	Payin Order Status Enum
`completionTime`	`date`	Completion time
`nonceStr`	`string(32)`	Random string
`patchOrderNo`	`string(32)`	The platform order number of the associated original order
`patchMchOrderNo`	`string(32)`	The merchant order number of the associated original order
`orderType`	`string(32)`	API=API order MCH=Merchant dashboard DESK=Paydesk order PATCH=PATCH order

Webhook Request Example

bash

curl -L 'merchant.com/webhooks/payin' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"amount":20000.00,"completionTime":"2024-12-02 12:07:06","fee":2500.0000,"mchOrderNo":"1386503284355244033","merchantId":"3002120","nonceStr":"1733116026894","orderNo":"PAYIN8551790545658687488","orderStatus":"SUCCESS","payCode":"OR.GPNQR..INOPROID_BS","payType":"41","payUrl":"https://payurl.com"}'

Webhooks Detail-APIWebhooks Detail-PATCH Order

json

{
  "amount": 1000.0,
  "completionTime": "2024-11-24 21:56:55",
  "fee": 2.0,
  "mchOrderNo": "order_xxxxxxxxxxxxxx",
  "merchantId": "1012345",
  "nonceStr": "1732507016285",
  "orderNo": "PAYIN1234500000000001",
  "orderStatus": "SUCCESS",
  "orderType": "API",
  "patchMchOrderNo": "order_xxxxxxxxxxxxxx",
  "patchOrderNo": "PAYIN1234500000000001",
  "payCode": "60088888888888",
  "payType": "69",
  "payUrl": "https://xxxxx.xxxx.com/xxx/xx/xxx"
}

json

{
  "amount": 1000.0,
  "completionTime": "2024-11-24 21:56:55",
  "fee": 2.0,
  "mchOrderNo": "order_xxxxxxxxxxxxxx",
  "merchantId": "2004015",
  "nonceStr": "1732507016285",
  "orderNo": "PAYIN1234500000000002",
  "orderStatus": "SUCCESS",
  "orderType": "PATCH",
  "patchMchOrderNo": "order_xxxxxxxxxxxxxx0001",
  "patchOrderNo": "PAYIN1234500000000001",
  "payCode": "60088888888888",
  "payType": "69"
}

Supplementary instructions when orderType is PATCH

If the user does not pay according to the order amount or pays repeatedly, a supplementary order will appear. In this case, the orderType of the supplementary order is PATCH:

orderNo is the platform order number newly generated for this order.
patchOrderNo is the platform order number of the associated original order,
patchMchOrderNo is the merchant order number of the associated original order.
mchOrderNo is the merchant order number of the associated original order (with a serial number identifier). Note that at this time, the serial number identifier will be added to the end of the mchOrderNo returned by the callback to distinguish multiple partial repayment orders.

The mchOrderNo you receive in the callback is MCH2023008800001, and so on.

When a patch order occurs, our robot will also notify the corresponding merchant group, and the notification will contain all the information you need.

When the orderType of the order is API:

patchOrderNo is the same as orderNo
patchMchOrderNo is the same as mchOrderNo

At this time, the above parameters have no additional meaning.

TIP

When the webhooks response HTTP status code is 200, 301 or 302, we believe that the merchant has successfully received and processed the callback. For other statuses, we believe that the merchant has failed to process the callback.

After the webhooks fails, it will be retried in 1, 2, 4, 8, 16, 32, 64, 128, 256, 512 minutes, and the webhooks will be retried 10 times in total

Create Payin Order ​

Query Payin Order ​

Async Webhook Notification ​

Create Payin Order

Query Payin Order

Async Webhook Notification