Payout Transaction
Info
GrubPay now facilitates USD transactions for sending money to your business partner. To integrate this functionality, please contact our customer service for assistance.
Payee
Payout transaction needs the pre-established payee information beforehand. The following endpoints allows merchants to Register, Query, Update, and Delete the payee's information.
Payee Status Dictionary
Status | Explanation |
---|---|
ACTIVATED | The account is ready for payout transaction. |
PENDING | The account information has been received and is currently under review, it is not yet available for transactions, more information might be needed. |
INVALID | The account details provided are incorrect or do not pass validation checks, please contact GrubPay for further assistance. |
Register Payee
Info
This endpoint allows the merchant in adding the payee and their funding account information, thereby enabling the payout transaction.
Endpoint
https://api.grubpay.io/v4/payout/payee_register
Method:
POST
Header
Content-Type: application/json;charset=UTF-8
Request
Name | Required | Type | Sample | Description |
---|---|---|---|---|
mchId | y | String | 10000701 | assigned by GrubPay |
loginName | y | String(12) | jack123 | merchant's login name |
payeeId | y | String | 1234567890abc | assigned by merchant |
profileType | y | String | INDIVIDUAL | BUSINESS or INDIVIDUAL(if BUSINESS, enter the contact person's dateOfBirth) |
company | y* | String | Demo Inc | payee's company name, only required if profileType = BUSINESS |
dateOfBirth | y | String | 1970-01-01 | payee's birthday, must be in the format: yyyy-mm-dd |
y | String | abcd@example.com | payee's email | |
firstName | y | String | John | payee's first name |
lastName | y | String | Smith | payee's last name |
phone | n | String | 1234567890 | payee's phone |
state | y | String | Washington | payee's state, can be the state code (e.g.WA) |
city | y | String | Portland | payee's city |
street | y | String | 123 example St | payee's street |
street2 | n | String | #201 | optional address field (can be used for unit number) |
zip | y | String | 000000 | payee's zip code |
accountNum | y | String | 1234**798 | bank account number |
routingNum | y | String | 0310**503 | bank account routing number |
accountType | y | String | ECHK | ECHK - checking account, ESAV - savings account |
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, payee detailed info returned |
retData
contains payee information:
name | required | type | sample | description |
---|---|---|---|---|
payeeKey | y | String | 2000300********5552 | assigned by GrubPay, required by all endpoints related to payee |
payeeId | y | String | 1234567890abc | assigned by merchant |
y | String | abcd@example.com | payee's email | |
createdTime | y | String | 2024-02-21 23:40:16 | timestamp for when the payee was registered |
firstName | y | String | John | payee's first name |
lastName | y | String | Smith | payee's last name |
payeeStatus | y | String | ACTIVATED | please see Payee Status Dictionary |
payeeToken | y | String | 2010300********6454 | payee's funding account's token |
Note
Please ensure to keep track of the payeeKey
as they are essential for processing payout transactions.
Query Payee
Info
This endpoint allows the merchant inquire about the status of a registered payee.
Endpoint
https://api.grubpay.io/v4/payout/payee_query
Method:
POST
Header
Content-Type: application/json;charset=UTF-8
Request
Name | Required | Type | Sample | Description |
---|---|---|---|---|
mchId | y | String | 10000701 | assigned by GrubPay |
payeeKey | y | String | 2000300********5552 | assigned by GrubPay, required by all endpoints related to payee |
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, payee detailed info returned |
retData
contains payee information:
name | required | type | sample | description |
---|---|---|---|---|
payeeKey | y | String | 2000300********5552 | assigned by GrubPay, required by all endpoints related to payee |
payeeId | y | String | 1234567890abc | assigned by merchant |
y | String | abcd@example.com | payee's email | |
createdTime | y | String | 2024-02-21 23:40:16 | timestamp for when the payee was registered |
updatedTime | y | String | 2024-02-21 23:53:16 | timestamp for when the payee was last updated |
firstName | y | String | John | payee's first name |
lastName | y | String | Smith | payee's last name |
state | y | String | Washington | payee's state |
city | y | String | Portland | payee's city |
street | y | String | 123 example St | payee's street |
street2 | n | String | #201 | optional address field |
zip | y | String | 000000 | payee's zip code |
phone | n | String | 1234567890 | payee's phone |
profileType | y | String | INDIVIDUAL | BUSINESS or INDIVIDUAL |
company | n | String | Demo Inc | payee's company name |
payeeStatus | y | String | ACTIVATED | please see Payee Status Dictionary |
payeeToken | y | String | 2010300********6454 | payee's funding account's token |
Update Payee
Info
This endpoint enables the merchant to update information for a payee already present in the system.
Endpoint
https://api.grubpay.io/v4/payout/payee_update
Method:
POST
Header
Content-Type: application/json;charset=UTF-8
Request
Name | Required | Type | Sample | Description |
---|---|---|---|---|
mchId | y | String | 10000701 | assigned by GrubPay |
loginName | y | String(12) | jack123 | merchant's login name |
payeeKey | y | String | 2000300********5552 | assigned by GrubPay, required by all endpoints related to payee |
payeeId | n | String | 1234567890abc | assigned by merchant |
profileType | n | String | INDIVIDUAL | BUSINESS or INDIVIDUAL |
company | y* | String | Demo Inc | payee's company name, only required when profileType = BUSINESS |
dateOfBirth | n | String | 1970-01-01 | payee's birthday must be in the format: yyyy-mm-dd |
firstName | n | String | John | payee's first name |
lastName | n | String | Smith | payee's last name |
phone | n | String | 1234567890 | payee's phone |
state | n | String | Washington | payee's state, can be the state code (e.g.WA) |
city | n | String | Portland | payee's city |
street | n | String | 123 example St | payee's street |
street2 | n | String | #201 | optional address field (can be used for unit number) |
zip | n | String | 000000 | payee's zip code |
accountNum | n | String | 1234**798 | bank account number |
routingNum | n | String | 0310**503 | bank account routing number |
accountType | n | String | ECHK | ECHK - checking account, ESAV - savings account |
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, payee detailed info returned |
retData
contains payee information:
name | required | type | sample | description |
---|---|---|---|---|
payeeKey | y | String | 2000300********5552 | assigned by GrubPay, required by all endpoints related to payee |
payeeId | y | String | 1234567890abc | assigned by merchant |
y | String | abcd@example.com | payee's email | |
createdTime | y | String | 2024-02-21 23:40:16 | timestamp for when the payee was registered |
updatedTime | y | String | 2024-02-21 23:53:16 | timestamp for when the payee was last updated |
firstName | y | String | John | payee's first name |
lastName | y | String | Smith | payee's last name |
state | y | String | Washington | payee's state |
city | y | String | Portland | payee's city |
street | y | String | 123 example St | payee's street |
street2 | n | String | #201 | optional address field |
zip | y | String | 000000 | payee's zip code |
phone | n | String | 1234567890 | payee's phone |
profileType | y | String | INDIVIDUAL | BUSINESS or INDIVIDUAL |
company | n | String | Demo Inc | payee's company name |
payeeStatus | y | String | ACTIVATED | please see Payee Status Dictionary |
payeeToken | y | String | 2010300********6454 | payee's funding account's token |
Delete Payee
Info
This endpoint allows the merchant to delete a payee from the system.
Endpoint
https://api.grubpay.io/v4/payout/payee_delete
Method:
POST
Header
Content-Type: application/json;charset=UTF-8
Request
Name | Required | Type | Sample | Description |
---|---|---|---|---|
mchId | y | String | 10000701 | assigned by GrubPay |
loginName | y | String(12) | jack123 | merchant's login name |
payeeKey | y | String | 2000300********5552 | assigned by GrubPay, required by all endpoints related to payee |
y | String | abcd@example.com | payee's email | |
sign | y | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Sign algorithm |
Response
name | Required | type | sample | description |
---|---|---|---|---|
retCode | y | String | SUCCESS or FAIL | |
retMsg | y | String | successfully deleted payee: 1234567890abc | |
retData | y | JSON | if retCode=SUCCESS, payee detailed info returned |
retData
contains deleted payee information:
name | required | type | sample | description |
---|---|---|---|---|
payeeKey | y | String | 2000300********5552 | assigned by GrubPay, required by all endpoints related to payee |
payeeId | y | String | 1234567890abc | assigned by merchant |
y | String | abcd@example.com | payee's email | |
createdTime | y | String | 2024-02-21 23:40:16 | timestamp for when the payee was registered |
updatedTime | y | String | 2024-02-21 23:53:16 | timestamp for when the payee was last updated |
firstName | y | String | John | payee's first name |
lastName | y | String | Smith | payee's last name |
state | y | String | Washington | payee's state |
city | y | String | Portland | payee's city |
street | y | String | 123 example St | payee's street |
street2 | n | String | #201 | optional address field |
zip | y | String | 000000 | payee's zip code |
phone | n | String | 1234567890 | payee's phone |
profileType | y | String | INDIVIDUAL | BUSINESS or INDIVIDUAL |
company | n | String | Demo Inc | payee's company name |
payeeStatus | y | String | ACTIVATED | please see Payee Status Dictionary |
payeeToken | y | String | 2010300********6454 | payee's funding account's token |
Payout Transfer
Info
This endpoint is responsible for executing the actual payout transaction.
Transfer Status Dictionary
Status | Explaination |
---|---|
pending | Request has been successfully received by the system. It is currently in the queue for processing. |
success | The transaction has been processed without any issues, and the funds have been credited to the recipient's account. |
failed | Request was not completed, and the funds were not deducted from the sender's account. (insufficient funds, incorrect payment details, etc) |
returned | Request was cancelled after it was initiated. This could occur if the recipient's account rejects the funds. |
Endpoint
https://api.grubpay.io/v4/payout/pay
Method:
POST
Header
Content-Type: application/json;charset=UTF-8
Request
Name | Required | Type | Sample | Description |
---|---|---|---|---|
mchId | y | String | 10000701 | assigned by GrubPay |
loginName | y | String(12) | jack123 | merchant's login name |
payeeKey | y | String | 2000300********5552 | assigned by GrubPay, required by all endpoints related to payee |
mchPayoutId | y | String | abcdefgh | The payment unique ID in the merchant's system |
amount | y | int | 1500 | in cents |
subject | n | String(64) | ||
body | n | String(250) | ||
channel | n | String | STANDARD_ACH | STANDARD_ACH or SAME_DAY_ACH |
notifyUrl | y | String | https://example.com/webhooks | merchant's webhook URL to receive transaction notifications |
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 payout transaction information:
name | required | type | sample | description |
---|---|---|---|---|
payeeKey | y | String | 2000300********5552 | assigned by GrubPay, payee of this payout transaction |
payOrderId | y | String | 123456789012345678 | assigned by GrubPay |
mchPayoutId | y | String | abcdefgh | The payment unique ID in the merchant's system |
createdTime | y | String | 2024-02-21 23:40:16 | timestamp for when the transcation was placed |
amount | y | int | 1500 | in cents |
status | y | String | pending | please see Transfer Status Dictionary |
payeeToken | y | String | 2010300********6454 | payee's funding account's token |
channel | y | String | STANDARD_ACH | STANDARD_ACH or SAME_DAY_ACH |
Query Payout Transaction
Info
This endpoint allows the merchant to query a payout transaction.
Endpoint
https://api.grubpay.io/v4/payout/query
Method:
POST
Header
Content-Type: application/json;charset=UTF-8
Request
Name | Required | Type | Sample | Description |
---|---|---|---|---|
mchId | y | String | 10000701 | assigned by GrubPay |
payOrderId | y | String | 123456789012345678 | assigned by GrubPay |
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, transaction detailed info returned |
retData
contains payout transaction information:
name | required | type | sample | description |
---|---|---|---|---|
mchId | y | String | 10000701 | assigned by GrubPay |
payeeKey | y | String | 2000300********5552 | assigned by GrubPay, payee of this payout transaction |
payOrderId | y | String | 123456789012345678 | assigned by GrubPay |
mchPayoutId | y | String | abcdefgh | The payment unique ID in the merchant's system |
currency | y | String | USD | Fixed to USD |
payType | y | String | payout | Fixed to payout |
createdTime | y | String | 2024-02-21 23:40:16 | timestamp for when the transcation was placed |
paySuccTime | y | String | 2024-02-21 23:59:59 | timestamp for when the transcation was completed |
amount | y | int | 1500 | in cents |
status | y | String | success | please see Transfer Status Dictionary |
payeeToken | y | String | 2010300********6454 | payee's funding account's token |
channel | y | String | STANDARD_ACH | STANDARD_ACH or SAME_DAY_ACH |