Cashy Docs Center

Create Payin Order

HTTP Request

API EndPoint

POST baseUrl + /api/payIn

Request Parameters

Parameter	Required	Type	Description	Example
`currency`	`Y`	`string(32)`	Currency code(`COP`)	COP
`payType`	`Y`	`int`	Payment Product Type	pls refer topayin-paytype-enum
`amount`	`Y`	`decimal(20,2)`	Amount `10000-5000000`	10000
`reusableStatus`	`Y`	`boolean`	Whether to allow repeated payments can only be false	false（false=Not allowed,true=Allow）
`mchOrderNo`	`Y`	`string(32)`	Merchant order number (should be unique in the merchant system)	mchOrderNo1234
`expireTime`	`Y`	`long`	Expire time（Unit: Seconds） default 24 hours	`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	Jeck
`phone`	`Y`	`string(32)`	Payer phonenumber	+57xxxxxxx
`email`	`Y`	`string(32)`	Payer phonenumber	`xyz@gamil.com`
`idType`	`Y`	`string(32)`	Payin Payer ID Type `payType=153 Optional`	pls refer toPayin Payer ID Type
`idCard`	`Y`	`string(32)`	Payer ID number `payType=153 Optional`
`userType`	`Y`	`string(16)`	User type `payType=157 Required`	pls refer toUser Type
`bankId`	`Y`	`int`	Bank id`payType=157 Required`	pls refer topayin-bank-list-query

Request Example

bash

curl -L 'baseUrl/api/payIn' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"amount":30000,"idType":"1","mchOrderNo":"order00000001","idCard":"1103412345","remark":"payin","nonceStr":"123456789","realName":"Julian","reusableStatus":false,"payType":154,"expireTime":3600,"phone":"573016612345","notifyUrl":"https://xxxx.com/testCallback","currency":"COP","userType":"1","email":"julianandresgonzalezpineda@gmail.com"}'

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

SuccessSome Error

json

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "1002001",
    "mchOrderNo": "order00000001",
    "orderNo": "PAYIN00000000000000000001",
    "payCode": "350-Rivotech-29231858-PAYIN00000000000000000001",
    "payUrl": "350-Rivotech-29231858-PAYIN00000000000000000001",
    "payDeskUrl": "https://testxxxxx.cashypro.com/index.html?PAYIN00000000000000000001",
    "amount": "30000",
    "orderFee": "800"
  }
}

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)`	Payin Order Status Enum
`completionTime`	`yyyy-MM-dd HH:mm:ss`	Completion time

Response Example

PayingSuccess

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
  }
}

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
  }
}

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
`orderStatus`	`string(32)`	Order status
`payUrl`	`string(32)`	Payment url
`payCode`	`string(32)`	Payment VA/QRCODE
`payType`	`string(32)`	Pay product type
`completionTime`	`yyyy-MM-dd HH:mm:ss`	Completion time
`nonceStr`	`string(32)`	Random string

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":"1002001","nonceStr":"1733116026894","orderNo":"PAYIN8551790545658687488","orderStatus":"SUCCESS","payCode":"OR.GPNQR..INOPROID_BS","payType":"41","payUrl":"https://payurl.com"}'

Webhooks-SuccessWebhooks-Fail

json

{
  "amount": 20000.0,
  "completionTime": "2024-12-02 12:07:06",
  "fee": 2500.0,
  "mchOrderNo": "1386503284355244033",
  "merchantId": "1002001",
  "nonceStr": "1733116026894",
  "orderNo": "PAYIN8551790545658687488",
  "orderStatus": "SUCCESS",
  "payCode": "OR.GPNQR..INOPROID_BS",
  "payType": "41",
  "payUrl": "https://payurl.com"
}

json

{
  "amount": 20000.0,
  "completionTime": "2024-12-02 12:07:06",
  "fee": 2500.0,
  "mchOrderNo": "1386503284355244033",
  "merchantId": "1002001",
  "nonceStr": "1733116026894",
  "orderNo": "PAYIN8551790545658687488",
  "orderStatus": "FAIL",
  "payCode": "OR.GPNQR..INOPROID_BS",
  "payType": "41",
  "payUrl": "https://payurl.com"
}

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 ​

HTTP Request ​

Query Payin Order ​

Async Webhook Notification ​

Create Payin Order

HTTP Request

Query Payin Order

Async Webhook Notification