Direct Method
Direct method allows you to tokenize a card or make a purchase without any UI involved with just one api call.
Endpoint
https://api.grubpay.io/v4/auth
Method:
POST
Header
Content-Type: application/json;charset=UTF-8
Direct Card Purchase
Prerequisite
In order to make requests to this api, it is required that :
- you are PCI compliant
OR - you have already tokenized a card
What is capture
Capture authorizes the transaction through to settlement and may be triggered during purchase request (see capture field in request below) 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 Direct Purchase which may help you when going through the documentation.
Request
| Name | Required | Type | Sample | Description |
|---|---|---|---|---|
| mchId | y | String | 10000701 | assigned by GrubPay |
| mchOrderNo | y | String | 1234567890abc | assigned by merchant |
| token | n (y if card info not present) | String | assigned by GrubPay | |
| cardNum | n (y if token not present) | String | 4223456789564532 | card number |
| expiryDate | n (y if token not present) | String | 0725 | format: MMYY |
| cvv | n (y if token not present) | String | 132 | card cvv |
| zip | n (y if token not present) | String | 71826 | card zip |
| 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 | fixed to: CC_CARD |
| capture | n | String | Y or N (default Y) | specify Y to capture the transaction for settlement if approved |
| 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 | y | String | 432567******2266 | |
| cardType | y | String | A = Amex D = Discover M = Mastercard N = Non-co-branded debit card V = Visa | |
| expiryDate | y | String | ||
| authNum | y | String | ||
| transNum | y | String | ||
| channel | y | String | CC_CARD | fixed value:CC_CARD |
Direct Card Tokenize
Prerequisite
In order to make requests to this api, it is required that you are PCI compliant
! Tip
After you receive access credentials (merchant id, login name, merchant key). You can step through the demo Direct Tokenize which may help you when going through the documentation.
Request
| Name | Required | Type | Sample | Description |
|---|---|---|---|---|
| mchId | y | String | 10000701 | assigned by GrubPay |
| cardNum | y | String | 4223456789564532 | card number |
| expiryDate | y | String | 0725 | format: MMYY |
| cvv | y | String | 786 | card cvv |
| zip | y | String | card holder's zip | |
| loginName | y | String(12) | jack123 | merchant's login name |
| channel | y | String | CC_CARD | fixed to: CC_CARD |
| 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, card detailed info returned along with token |
retData contains following information:
| Name | Required | Type | Sample | Description |
|---|---|---|---|---|
| cardNum | y | String | 478825*************1443 | card number |
| expiryDate | y | String | 0725 | format: MMYY |
| cvv | y | String | 786 | card cvv |
| zip | y | String | 12345 | card postal code |
| token | y | String(50) | cf6e8f3f-c010-4b99-9a9f-32cf21ea7cb6 | reusable card token |
| pan | y | String(50) | 896a38b73df44c2e0da633b4c3843b51 | primary account number; a unique identifier for card |
Direct ACH Transfer
Tip
ACH transactions are automatically captured upon authorization
Request
| Name | Required | Type | Sample | Description |
|---|---|---|---|---|
| mchId | y | String | 10000701 | assigned by GrubPay |
| mchOrderNo | y | String | 1234567890abc | assigned by merchant |
| token | n (y if ACH account info not present) | String | assigned by GrubPay | |
| name | n (y if token not present) | String | Smith John | account holder name |
| accountType | n (y if token not present) | String | ECHK | ECHK - Electronic checking account, ESAV - Electronic savings account |
| routingNum | n (y if token not present) | String | 0310**503 | bank account routing number |
| accountNum | n (y if token not present) | String | 1234**798 | bank account number |
| 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_ACH | fixed to: CC_ACH |
| 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 |
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 | AC20221208005200944617628872 | |
| mchId | y | String | ||
| mchOrderNo | y | String | ||
| token | y | String | cf6e8f3f-c010-4b99-9a9f-32cf21ea7cb6 | reusable card token |
| acctNum | y | String | 031000*********6798 | provided account number |
| originalOrderId | n | String | original pay order id if payType="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 | |
| paySuccTime | y | String | 2021-04-07 19:44:51 | |
| authNum | y | String | ||
| transNum | y | String | ||
| sign | y | String | C380BEC2BFD727A4B6845133519F3AD6 | Sign algorithm |
Direct ACH Tokenize
Note
Please be aware that this function requires a different API endpoint URL as for now.
Note that this operation may incur a fee of $1.
You can alternatively obtain an ACH token as part of retData following a successful ACH transfer.
Endpoint
https://api.grubpay.io/v4/ach_tokenize
Method:
POST
Header
Content-Type: application/json;charset=UTF-8
Request
| Name | Required | Type | Sample | Description |
|---|---|---|---|---|
| mchId | y | String | 10000701 | assigned by GrubPay |
| routingNum | y | String | 0310**503 | bank account routing number |
| accountNum | y | String | 1234**798 | bank account number |
| accountType | y | String | ECHK | ECHK - Electronic checking account, ESAV - Electronic savings account |
| name | y | String | Smith John | account holder name |
| loginName | y | String(12) | jack123 | merchant's login name |
| channel | y | String | CC_ACH | fixed to: CC_ACH |
| 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, card detailed info returned along with token |
retData contains following information:
| Name | Required | Type | Sample | Description |
|---|---|---|---|---|
| routingNum | y | String | 0310**503 | bank account routing number |
| accountNum | y | String | 1234**798 | bank account number |
| accountType | y | String | ECHK | ECHK - Electronic checking account, ESAV - Electronic savings account |
| name | y | String | Smith John | account holder name |
| token | y | String(50) | cf6e8f3f-c010-4b99-9a9f-32cf21ea7cb6 | reusable ACH account token |