Subscription
Creating subscriptions
Endpoint
https://api.grubpay.io/v4/auth
Method:
POST
Header
Content-Type: application/json;charset=UTF-8
Important
If startDate is not included in the request: a startDate of the current date will be configured for this subscription and a payment will be made immediately with proceeding payments following the recurring frequency
Request
| Name | Required | Type | Sample | Description |
|---|---|---|---|---|
| mchId | y | String | 10000701 | assigned by GrubPay |
| mchOrderNo | y | String | 1234567890abc | assigned by merchant |
| token | y | String | assigned by GrubPay | |
| recurring | y | String | [w,2w,4w,m] | current possible configurations are weekly, bi-weekly,every 4 weeks (28 days) or monthly (set day each given month) |
| startDate | n | Int | 1684145800 | the UNIX timestamp (seconds) for the first recurring payment; ie. 1684145800 => Mon May 15 2023 10:16:40 GMT+0000. Recurring payments default to the closest half hour if startDate not supplied |
| amount | y | Int | 1500 | must > 0 |
| currency | y | String(3) | USD | fixed to: USD |
| loginName | y | String(12) | jack123 | merchant's login name |
| subject | n | String(64) | ||
| body | n | String(250) | ||
| channel | y | String | CC_CARD | CC_ACH | |
| capture | y | String | Y | |
| notifyUrl | y | String(200) | http://sample.com/notify | merchant endpoint for receiving recurring transaction notifications, must be http or https |
| sign | y | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Sign algorithm |
Response
| name | required | type | sample | description |
|---|---|---|---|---|
| retCode | y | String | SUCCESS or FAIL | |
| retMsg | y | String | ||
| retData | y | JSON | if retCode=SUCCESS, order detailed info returned |
retData contains order information:
| name | required | type | sample | description |
|---|---|---|---|---|
| payOrderId | y | String | SUCCESS or FAIL | |
| mchId | y | String | ||
| mchOrderNo | n | String | ||
| originalOrderId | n | String | original pay order id for refund | |
| amount | y | Int | 100 | in cents |
| currency | y | String | CAD | |
| payType | y | String | pay or refund | |
| refundable | y | Int | 100 | in cents |
| status | y | Int | 0,1,2,9 | 0 = pending order, 1 = unknown, 2 = success, 9 = fail |
| recurringId | y | Int | recurring payment id this transaction belongs to ( 0 if non-recurring) | |
| paySuccTime | y | String | 2021-04-07 19:44:51 | |
| cardNum | n | String | 432567******2266 | |
| cardType | n | String | A = Amex D = Discover M = Mastercard N = Non-co-branded debit card V = Visa (card payments only) | |
| expiryDate | n | String | ||
| authNum | y | String | ||
| transNum | y | String | ||
| channel | y | String | CC_CARD | CC_ACH |
Subscription Details
To check the metadata of a subscription
Endpoint
https://api.grubpay.io/v4/recurring
Method:
POST
Header
Content-Type: application/json;charset=UTF-8
Request
| name | required | type | sample | description |
|---|---|---|---|---|
| mchId | y | String | 10000701 | assigned by GrubPay |
| token | y | String(50) | cf6e8f3f-c010-4b99-9a9f-32cf21ea7cb6 | reusable token |
| sign | y | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Sign algorithm |
Response
| name | required | type | sample | description |
|---|---|---|---|---|
| retCode | y | String | SUCCESS or FAIL | |
| retMsg | y | String | ||
| retData | y | JSON | if retCode is SUCCESS, recurring payment(s) detailed info returned |
retData contains order information:
| name | required | type | sample | description |
|---|---|---|---|---|
| id | y | String | ||
| mid | y | String | merchant id | |
| amount | y | Int | 100 | in cents |
| token | y | String(50) | cf6e8f3f-c010-4b99-9a9f-32cf21ea7cb6 | reusable token |
| frequency | y | String | [w,2w,4w,m] | current possible configurations are weekly, bi-weekly,every 4 weeks (28 days) or monthly (set day each given month) |
| start_date | y | String | payment start date in UTC time | |
| last_paid | y | String | last payment date in UTC time, defaults to "1970-01-01" if no payment has been made yet | |
| last_payment | y | String | PC20221123224002378248641620 | payorderid of last payment or of new order if no payment has been made yet |
| next_payment | y | String | date of next scheduled payment in UTC time |
Cancel Subscription
To stop a subscription
Endpoint
https://api.grubpay.io/v4/cancel_recurring
Method:
POST
Header
Content-Type: application/json;charset=UTF-8
Request
| name | required | type | sample | description |
|---|---|---|---|---|
| mchId | y | String | 10000701 | assigned by GrubPay |
| recurringId | y | Int | 12 | recurring payment id |
| loginName | y | String(12) | jack123 | merchant's login name |
| sign | y | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Sign algorithm |
Response
| name | required | type | sample | description |
|---|---|---|---|---|
| retCode | y | String | SUCCESS or FAIL | |
| retMsg | y | String | Successfully deleted recurring #255 | |
| retData | y | JSON | if retCode is SUCCESS, recurring payment detailed info returned |