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

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

# Payout Transaction

# Payee

# Payee Status Dictionary

# Register Payee

# Endpoint

# Method:

# Header

# Request

# Response

# retData contains payee information:

# Query Payee

# Endpoint

# Method:

# Header

# Request

# Response

# retData contains payee information:

# Update Payee

# Endpoint

# Method:

# Header

# Request

# Response

# retData contains payee information:

# Delete Payee

# Endpoint

# Method:

# Header

# Request

# Response

# retData contains deleted payee information:

# Payout Transfer

# Transfer Status Dictionary

# Endpoint

# Method:

# Header

# Request

# Response

# retData contains payout transaction information:

# Query Payout Transaction

# Endpoint

# Method:

# Header

# Request

# Response

# retData contains payout transaction information:

Payout Transaction

Payee

Payee Status Dictionary

Register Payee

Endpoint

Method:

Header

Request

Response

`retData` contains payee information:

Query Payee

Endpoint

Method:

Header

Request

Response

`retData` contains payee information:

Update Payee

Endpoint

Method:

Header

Request

Response

`retData` contains payee information:

Delete Payee

Endpoint

Method:

Header

Request

Response

`retData` contains deleted payee information:

Payout Transfer

Transfer Status Dictionary

Endpoint

Method:

Header

Request

Response

`retData` contains payout transaction information:

Query Payout Transaction

Endpoint

Method:

Header

Request

Response

`retData` contains payout transaction information: