Redirected Integration
How It Works
Endpoint
https://api.grubpay.io/v4/auth
Method:
POST
Header
Content-Type: application/json;charset=UTF-8
Card Purchase Guide
What is capture
Capture authorizes the transaction through to settlement and may be triggered during purchase request (see capture field in the request) or some time after the initial authorization is submitted via Capture api.
! Tip
After you receive access credentials (merchant id, login name, merchant key). You can step through the demo Card Purchase which may help you when going through the documentation.
1. Request to Endpoint with format below
Request
| Name | Required | Type | Sample | Description |
|---|---|---|---|---|
| mchId | y | String | 10000701 | assigned by GrubPay |
| mchOrderNo | y | String | 1234567890abc | assigned by merchant |
| amount | y | Int | 1500 | in cents; 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 | fixed to: CC_CARD |
| capture | n | String | Y or N (default Y) | specify Y to capture the transaction for settlement if approved |
| returnUrl | y | String(200) | http://sample.com/return | merchant url to redirect after order submit, must be http or https |
| sign | y | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Sign algorithm |
2. Redirect to `redirectUrl` in response below to GrubPay payment page
Sample redirect url: https://api.grubpay.io/auth?secureId=8ca3658204023b27eb998197165142eb6193868cfa730edc81b0877640c58f8c
Response
| name | Required | type | sample | description |
|---|---|---|---|---|
| retCode | y | String | SUCCESS or FAIL | |
| retMsg | y | String | ||
| retData.redirectUrl | y* | String | *if retCode is SUCCESS and valid `returnUrl` is present in request |
3. After customer submit GrubPay form, payment page will automatically redirect to merchant supplied `returnUrl` with following parameters
Sample return url: https://example.com/return?payOrderId=xxx&status=2&retCode=xxxxxxx&retMsg=xxxxxxxx
| name | Required | type | sample | description |
|---|---|---|---|---|
| payOrderId | y | String | PC20221125212844814733300243 | |
| mchOrderNo | y | String | 1669411724 | |
| status | y | Int | 0,1,2,9 | 0 = pending order, 1 = unknown, 2 = success, 9 = fail |
| retMsg | y | String | ||
| retCode | y* | String | *if retCode is SUCCESS and valid `returnUrl` is present in request | |
| retMsg | y | String |
4. (Recommended) Merchant queries transaction with returned `payOrderId` and handle response accordingly
For details see Query Transaction
Card Tokenize Guide
Info
GrubPay provides encryption and tokenization services with a secure data vault typically used to store payment card Primary Account Numbers in a PCI-DSS compliant manner. GrubPay generates a unique and random token value to be used by your application instead of a clear or encrypted PAN, potentially reducing your PCI scope considerably.
! Tip
After you receive access credentials (merchant id, login name, merchant key). You can step through the demo Card Tokenize which may help you when going through the documentation.
1. Request to Endpoint with format below
Request
| Name | Required | Type | Sample | Description |
|---|---|---|---|---|
| mchId | y | String | 0000701 | assigned by GrubPay |
| loginName | y | String(12) | jack123 | merchant's login name |
| channel | y | String | CC_CARD | fixed to: CC_CARD |
| returnUrl | y | String(200) | merchant url to redirect after order submit | |
| sign | y | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Sign algorithm |
2. Redirect to `redirectUrl` in response to see GrubPay card form
Sample redirect url: https://api.grubpay.io/auth?secureId=8ca3658204023b27eb998197165142eb6193868cfa730edc81b0877640c58f8c
3. After customer submit GrubPay form, payment page will automatically redirect to merchant supplied `returnUrl` with following parameters
Sample return url: https://example.com/return?token=xxx&retCode=xxxxxxx&retMsg=xxxxxxxx
| name | Required | type | sample | description |
|---|---|---|---|---|
| token* | y | String(36) | 5caeca18-4a54-49d1-af48-85e42af9a8ab | *if retCode is SUCCESS and valid `returnUrl` is present in request |
| retMsg | y | String | ||
| retCode | y | String |
4. You can now use this token for future purchases
ACH Transfer Guide
Tip
ACH transactions are automatically captured upon authorization. There is no tokenization api, tokens for direct method are created upon successful ACH transfer.
1. Request to Endpoint with format below
Request
| Name | Required | Type | Sample | Description |
|---|---|---|---|---|
| mchId | y | String | 10000701 | assigned by GrubPay |
| mchOrderNo | y | String | 1234567890abc | assigned by merchant |
| amount | y | Int | 1500 | in cents; 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_ACH | fixed to: CC_ACH |
| returnUrl | y | String(200) | http://sample.com/return | merchant url to redirect after order submit, must be http or https |
| notifyUrl | y | String(200) | http://sample.com/notify | merchant endpoint for receiving ACH transaction notifications , must be http or https |
| sign | y | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Sign algorithm |
2. Redirect to `redirectUrl` in response below to GrubPay payment page
Sample redirect url: https://api.grubpay.io/auth?secureId=8ca3658204023b27eb998197165142eb6193868cfa730edc81b0877640c58f8c
Response
| name | Required | type | sample | description |
|---|---|---|---|---|
| retCode | y | String | SUCCESS or FAIL | |
| retMsg | y | String | ||
| retData.redirectUrl | y* | String | *if retCode is SUCCESS and valid `returnUrl` is present in request |
3. After customer submit GrubPay form, payment page will automatically redirect to merchant supplied `returnUrl` with following parameters
Sample return url: https://example.com/return?payOrderId=xxx&status=2&retCode=xxxxxxx&retMsg=xxxxxxxx
| name | Required | type | sample | description |
|---|---|---|---|---|
| payOrderId | y | String | PC20221125212844814733300243 | |
| mchOrderNo | y | String | 1669411724 | |
| status | y | Int | 0,1,2,9 | 0 = pending order, 1 = unknown, 2 = success, 9 = fail |
| retMsg | y | String | ||
| retCode | y* | String | *if retCode is SUCCESS and valid `returnUrl` is present in request | |
| retMsg | y | String |
4. (Recommended) Merchant queries transaction with returned `payOrderId` and handle response accordingly
For details see Query Transaction