About GetDisbursementData
This API provides the details on how a payment is made once a bill is paid via Bill.com using the PayBills API. The disbursementStatus
parameter is empty until the funds are transferred to the respective vendor's bank account.
The response you get depends on how the payment was sent to the vendor. You can identify the payment type with the paymentType
parameter in the response.
Payment type | paymentType value |
---|---|
Check | 0 |
ACH to Large Billers | 1 |
ACH | 2 |
PayPal | 3 |
International ePayment | 5 |
Vendor Direct (VCard) | 7 |
Instant Transfer (Wallet) | 9 |
Note: paymentType
is 9 for all payment options available to a Basic Receivables vendor: ACH (default), Instant Transfer (Wallet), and International ePayment (only for non-US Basic Receivables vendor).
Example
Request
<API_URL_EndPoint>/GetDisbursementData.json
data={
"sentPayId" : "stp01GYJJUIAXICXp5td"
}
Check
A paper check payment is sent to the vendor.
Response
{
"response_status" : 0,
"response_message" : "Success",
"response_data" : {
"paymentType" : "0",
"disbursementStatus" : "3",
"checkData" : {
"checkNumber" : 789793717,
"checkDate" : "2021-10-09",
"arrivesByDate" : "2021-10-15",
"clearedDate" : "2021-10-10",
"amount" : 15.00,
"memo" : "Inv #VAA300",
"expirationDate" : "2022-06-08",
"trackingInfo" : null,
"errorCode" : null
}
}
}
ACH to Large Billers
An ePayment via ACH is sent to the vendor in Bill.com’s Large Biller Network.
Response
{
"response_status" : 0,
"response_message" : "Success",
"response_data" : {
"paymentType" : "1",
"disbursementStatus" : "3",
...
// Vendor address information
...
"rppsData" : {
"arrivesByDate" : "2021-10-14",
"sentDate" : "2021-10-10",
"errorCode" : null,
"largeBillerId" : 4903927258,
"returnedDate" : null,
"traceNumber" : 1161
}
}
}
ACH
An ePayment via ACH is sent to the vendor.
Response
{
"response_status" : 0,
"response_message" : "Success",
"response_data" : {
"paymentType" : "2",
"disbursementStatus" : "3",
"achData" : {
"depositDate" : "2021-10-13",
"routingNumber" : "*****1054",
"accountNumber" : "******4455",
"sentDate" : "2021-10-10",
"errorCode" : null,
"returnedDate" : null,
"uniqueId" : "014DPQMXGIJDHT8"
}
}
}
PayPal
The vendor must have a PayPal account.
Response
{
"response_status" : 0,
"response_message" : "Success",
"response_data" : {
"paymentType" : "3",
"disbursementStatus" : "3",
"payPalData" : {
"senderEmail" : "senderemail@domain.com",
"receiverEmail" : "receivedemail@domain.com",
"txnStatus" : "0",
"pendingReason" : "0",
"voidReason" : "0",
"voidMessage" : null
}
}
}
International ePayment
International ePayment is an ePayment made to the vendor in a non-US location.
Response
{
"response_status" : 0,
"response_message" : "Success",
"response_data" : {
"paymentType" : "5",
"disbursementStatus" : "0",
"vcardReissueReason" : "0",
"vendorName" : "Happy Music Supplies Canada",
"orgName" : "One Musical",
...
// Vendor address information
...
"combinedStatus" : 4,
"isVoidable" : true,
"isVoidableFromUI" : true,
"intlEPmtData" : {
"arrivesByDate" : "2021-10-13",
"routingNumber" : "000307626",
"accountNumber" : "***4567",
"localAmount" : 5.00,
"sentDate" : "2021-10-10",
"traceNumber" : null,
"errorCode" : null,
"returnedDate" : null,
"vendorBankData" : "{vendor_bank_information}",
"confirmId" : null,
"confirmDate" : null,
"confirmMsg" : null,
"confirmStatus" : "1",
"intlEPmtType" : "1"
}
}
}
Vendor Direct (VCard)
Vendor Direct (VCard) is an ePayment method where the eligible vendor receives a single-use virtual card and is processed like a credit card.
Response
{
"response_status" : 0,
"response_message" : "Success",
"response_data" : {
"paymentType" : "7",
"disbursementStatus" : "3",
"vcardReissueReason" : "0",
"vendorName" : "Happy Music Supplies",
"orgName" : "One Musical",
"combinedStatus" : 11,
"isVoidable" : true,
"isVoidableFromUI" : false,
"vcardData" : {
"status" : "1",
"tokenExpiration" : "08/11/2021",
"maskedCardNumber" : "",
"cardIssueDate" : "2021-07-12",
"settlementDate" : null,
"arrivesByDate" : "2021-07-12",
"vcardAccountNumber" : "5405240724600665",
"maskedVcardAccountNumber" : "************0665",
"cvv" : "665",
"vcardExpiration" : "2024-07-31",
"vcardAuthorizedDate" : null,
"remitEmail" : "payable@happymusic.com",
"zipCode" : "94303"
...
// Other fields (if any) for VCard suppliers
...
}
}
}
Instant Transfer (Wallet)
Instant Transfer (Wallet) is an ePayment option that the eligible vendor can select. If the vendor selects this option, they pay a 1% fee to receive the payment.
Response
{
"response_status" : 0,
"response_message" : "Success",
"response_data" : {
"paymentType" : "9",
"disbursementStatus" : "3",
"vcardReissueReason" : "0",
"vendorName" : "Happy Music Supplies",
"orgName" : "One Musical",
"combinedStatus" : 12,
"isVoidable" : false,
"isVoidableFromUI" : false,
"walletData" : {
"depositDate" : "2021-07-13",
"transactId" : "1c338f7d-4725-4c35-9524-9cdfc09ca6bb",
"receivedPayId" : "0rp02IPBHIASAFJX1ipc"
}
}
}
Not disbursed
If the payment is scheduled and not yet disbursed, the response is empty. See Payables payment timing for more information about disbursement times for different payment types.
Response
{
"response_status" : 0,
"response_message" : "Success",
"response_data" : {
}
}
Error Codes
Checks
Error code | Status | Description |
E01 | Expired | Expired. The submitted check expired before being cashed (after 90 days). |
E02 | Returned | Returned. The check could not be processed and is returned to account holder for reasons, such as insufficient funds, lack of authorization, account closed/frozen, altered item, or invalid vendor address. |
ACH
Standard National Automated Clearing House Association (NACHA) ACH error codes.
Resources
Parameters
Field Name | Description | Required? |
---|---|---|
sentPayId | The system generated ID of the payment scheduled via Bill.com. | Yes |
Check payment parameters
Field Name | Type | Description |
---|---|---|
paymentType | Enum | Value for check payment is 0 |
disbursementStatus | Enum |
Payment status 0 = Scheduled, 3 = Done, 4 = Failed, 5 = Void, 6 = Hold |
checkNumber | VendorID | Number on the check sent to vendor |
checkDate | Date | Date printed on the check |
arrivesByDate | Date | Estimated date when the vendor receives the check |
clearedDate | Date | Date when the check is cashed by the vendor and cleared |
amount | Currency | Check amount |
memo | String | Payment description memo sent to vendor |
expirationDate | Date | Check expiration date. After this date, the check is automatically voided and the funds are returned to the sender's bank account. |
trackingInfo | String | Tracking information for faster check payment options |
errorCode | String | Error code if the check is returned or if there are other issues with check delivery |
ACH to Large Billers parameters
Field Name | Type | Description |
---|---|---|
paymentType | Enum |
Value for ACH payment to Large Billers is 1 |
disbursementStatus | Enum |
Payment status 0 = Scheduled, 3 = Done, 4 = Failed, 5 = Void |
arrivesByDate | Date | Date when the ACH payment arrives in the vendor bank account |
sentDate | Date | Date when the ACH payment is sent to the vendor bank account |
errorCode | String | Error code if the payment disbursement fails |
largeBillerId | Number | System generated ID of the biller in Large Biller network |
returnedDate | Date | Date when the payment is returned (if an error is thrown) |
traceNumber | String | Number to track the payment (if an error is thrown) |
ACH parameters
Field Name | Type | Description |
---|---|---|
paymentType | Enum |
Value for ACH payment is 2. The |
disbursementStatus | Enum |
Payment status 0 = Scheduled, 3 = Done, 4 = Failed, 5 = Void |
depositDate | Date | Date when the ACH payment arrives in the vendor bank account |
routingNumber | Number | Vendor routing number. This value is encrypted. |
accountNumber | Number | Vendor bank account. This value is encrypted. |
sentDate | Date | Date when the ACH payment is sent to the vendor bank account |
errorCode | String | NACHA error code if the ACH payment is returned |
returnedDate | Date | Date when the ACH payment is returned (if an error is thrown) |
uniqueId | String | ACH payment unique ID |
PayPal parameters
Field Name | Type | Description |
---|---|---|
paymentType | Enum | Value for PayPal payment is 3 |
disbursementStatus | Enum |
Payment status 0 = Scheduled, 3 = Done, 4 = Failed, 5 = Void |
senderEmail | String | Sender PayPal account email address |
receiverEmail | String | Receiver PayPal account email address or vendor email address |
txnStatus | String | PayPal transaction status |
pendingReason | String | PayPal payment pending reason (if the payment is pending) |
voidReason | String | Void reason code (if the payment is voided) |
voidMessage | String | Void reason (if the payment is voided) |
See pending_reason
in the PayPal Developer guide for more information about PayPal payment pending reasons.
International ePayment parameters
Field Name | Type | Description |
---|---|---|
paymentType | Enum |
Value for International ePayment is 5. The |
disbursementStatus | Enum |
Payment status 0 = Scheduled, 3 = Done, 4 = Failed, 5 = Void, 7 = FxHold |
vcardReissueReason | Enum |
Reason why the payment is reissued 0 = None, 1 = Org opt out, 2 = Vendor opt out, 3 = International ePayment expired, 4 = Bill.com forced reissue, 5 = Payer reissues International ePayment, 6 = Payer reissues another payment type |
arrivesByDate | Date | Date when the payment is sent to the vendor |
routingNumber | Number | International vendor routing number |
accountNumber | Number | Masked international vendor account number |
localAmount | Currency | Payment amount in foreign currency |
sentDate | Date | Date when the payment is sent to the vendor bank account |
traceNumber | Number | Number to track the payment (if an error is thrown) |
errorCode | String | Error code if the payment disbursement fails |
returnedDate | Date | Date when the payment is returned (if an error is thrown) |
vendorBankData | String | International vendor bank information. There is no vendor bank information for Basic Receivables vendors. |
confirmId | String | Payment confirmation unique ID |
confirmDate | Date | Date when the payment confirmation is sent to the international vendor |
confirmMsg | String | Payment confirmation message sent to the international vendor |
confirmStatus | Enum |
Payment confirmation status 0 = Pending, 1 = Retrieved, 2 = Failed |
intlEPmtType | Enum |
International ePayment type 0 = None, 1 = Wire, 2 = International ACH |
Vendor Direct (VCard) parameters
Field Name | Type | Description |
---|---|---|
paymentType | Enum |
Value for Vendor Direct (VCard) payment is 7 |
disbursementStatus | Enum |
Payment status 0 = Scheduled, 3 = Done, 4 = Failed, 5 = Void |
vcardReissueReason | Enum |
Reason why the payment is reissued 0 = None, 1 = Org opt out, 2 = Vendor opt out, 3 = VCard expired, 4 = Bill.com forced reissue, 5 = Payer reissued VCard payment, 6 = Payer reissued payment using another payment type |
status | String | VCard payment status |
tokenExpiration | Date | Date when the VCard token expires. The VCard token expiry date is the last day of the next month after the VCard issue date. Bill.com reissues a token on the 20th day after the VCard is issued. |
cardIssueDate | Date | Date when the VCard is issued |
settlementDate | Date | Date when the VCard payment is settled after disbursement |
arrivesByDate | Date | Date when the VCard payment arrives in the vendor’s email inbox |
vcardAccountNumber | Number | VCard account number |
maskedVcardAccountNumber | Number | Masked VCard account number |
cvv | String | VCard CVV |
vcardExpiration | Date | VCard expiration date |
vcardAuthorizedDate | Date | Date when the VCard payment is authorized through the receiver’s merchant card processing system. A VCard payment can be voided only before the authorized date. |
remitEmail | String |
VCard payment receiver’s email address |
zipCode | String | VCard payment sender's zip code. This is Bill.com’s zip code. |
Instant Transfer (Wallet) parameters
Field Name | Type | Description |
---|---|---|
paymentType | Enum |
Value for Instant Transfer (Wallet) payment is 9. The |
disbursementStatus | Enum |
Payment status 0 = Scheduled, 3 = Done, 4 = Failed, 5 = Void |
vcardReissueReason | Enum |
Reason why the payment is reissued 0 = None, 1 = Org opt out, 2 = Vendor opt out, 3 = Instant Transfer payment expired, 4 = Bill.com forced reissue, 5 = Payer reissued Instant Transfer payment, 6 = Payer reissued payment using another payment type |
depositDate | Date | Date when the Instant Transfer payment is sent to the vendor |
transactId | String | Instant Transfer payment unique ID |
receivedPayId | String | ReceivedPay id generated for the Instant Transfer payment |
Parameter definitions
disbursementStatus values:
Value | Description |
---|---|
0 = Scheduled | The SentPay status value is Paid, but the amount is not yet disbursed from Bill.com to the vendor. The disbursement status is 0 on the SentPay process date after midnight. |
3 = Done | See Payables payment timing for more information about disbursement times for different payment types. The disbursement status is Done when the payment is disbursed from Bill.com to the vendor. |
4 = Failed | Disbursement failure. The reasons are specific to paymentType, such as a returned check, returned ACH disbursement, or returned/rejected RPPS disbursement. |
5 = Void | A previously disbursed payment (disbursementStatus = 3) is voided for reasons, such as void and reissue, void and refund, or expired (processed as void and refund). |
6 = Hold | The Bill.com operations team has put the disbursed payment on hold. |
7 = FxHold | The Bill.com operations team has put the disbursed International ePayment (paymentType = 5) on hold for foreign currency trading. |