Payments: Implementation

In this section, we list the implementation details for the Payments Element. This includes pre-conditions, custom events, and error handling.

Preconditions

BILL has a set of pre-conditions for working with the Payments Element.

Setup

Ensure that your setup is complete before working with the Payments Element.

Setup	Description
Set up organizations and users	You must set up your organizations and users with the BILL v3 API. See Organizations for BILL partners and Users for BILL partners for more information.
Onboard the organization	The organization onboarding must be complete with the Onboarding Element.
MFA	MFA is required for the user to schedule a payment. When the signed-in user session is not MFA-trusted, the user is prompted to complete MFA and create a trusted session in the Schedule Payment Element within the Payments Element. MFA setup is also available with the MFA Element. See MFA Element for more information.
Add a funding payment method	A valid funding payment method must be available for the user to schedule a payment.
Add a vendor	A vendor record must be available for the user to schedule a payment.
Add a payment	A payment must be scheduled for the user to view and manage the payment in the list of payments.

Required credentials

The Payments Element requires a set of credentials.

Credential	Description
`devKey`	Developer key generated with your BILL developer account.
`sessionId`	API session ID generated with `POST /v3/partner/login`. See API partner login in the API reference to learn about signing in and generating a partner-level `sessionId`.
`userId`	BILL-generated ID of the signed-in user. The value begins with `006`.
`orgId`	Organization ID associated with the signed-in user.

Email notifications

BILL sends a set of email notifications for different triggers with the Payments Element.

Name	Trigger	Description
Payment scheduled	Payment scheduled to a vendor	Inform the organization that a payment for a specific amount has been scheduled to their vendor on a specific date.
Void Successful	BILL successfully voided the payment	Notify the organization that a payment was successfully voided, as requested by the user.
Void failed	BILL was unable to void the payment	Notify the organization that a payment void failed, as requested by the user, and provide the reason.
Credit failed	BILL was unable to credit the organization for a payment	Notify the organization that a payment credit failed and provide the reason.
Void and reissue	BILL successfully voided and reissued the payment	Notify the organization that a payment was successfully voided and reissued, as requested by the user.
Void and credit	BILL successfully voided and credited the payment	Notify the organization that a payment was successfully voided and credited, as requested by the user.
Check return	A check payment sent to a vendor was returned	Notify the organization that a check sent to their vendor was returned and provide next steps.
Check expired	A check payment sent to a vendor expired	Notify the organization that a check payment to their vendor expired because it was not cashed within 90 days of the issue date, and provide next steps.
Virtual card expired	A virtual card sent to a vendor expired	Notify the organization that a virtual card sent to their vendor expired because it was not cashed within 20 days of the issue date, and provide next steps.
Failed payment	A payment failed due to incorrect account details	Notify the organization that a payment failed due to an incorrect routing or account number and provide resolution steps.
Failed payment	BILL was unable to send a payment and credited the organization's account	Notify the organization that a payment failed and, as a result, their bank account has been credited.
Failed payment	A payment failed due to an incorrect address	Notify the organization that a payment failed due to an incorrect address and provide resolution steps.
Funding failed, action required	Funding for a sent payment failed	Notify the organization that funding for a sent payment failed and request a wire transfer to resolve it.
Partial refund	A vendor processed only part of a payment	Notify the organization that their vendor processed only part of a payment and, as a result, the organization has been credited for the remaining balance.
Payment arrival date updated	The estimated arrival date for a scheduled payment changed	Notify the organization that a payment’s estimated arrival date has been changed.
Payment on the way (Vendor notification)	The organization sent a payment to the vendor	Inform the vendor that a payment is on the way.
Payment delivered (Vendor notification)	A payment from the organization was delivered	Notify the vendor that a payment from the organization has been deposited or received.
Virtual card sent (Vendor notification)	The organization sent a virtual card payment to the vendor	Inform the vendor that the organization has sent them a virtual card payment and provides details on how to cash it.

Initialization

In the <body> tag of your web page, complete the Element initialization script in your <script> tag. Set name as payments for the Payments Element. See Initialize the Element experience for more information.

// Initialize & mount the Element on the web page
    const bootloader = init(billBootConfig);
    bootloader.register({
      id: 'element1',
      name: 'payments'
    });
    await bootloader.render('element1', '#your-div');

Events

BILL provides a set of custom Element properties that you can set. You can use window.addEventListener or an onEvent callback for listening to and handling events.

Ready events

The Ready events fire when the Element renders successfully.

`paymentsListReady`

The paymentsListReady event is emitted when the Payment List page is rendered successfully.

// Empty payload
{
  "name": "paymentsListReady",
  "payload": {}
}

`paymentDetailsReady`

The paymentDetailsReady event is emitted when the Payment Details page is rendered successfully.

{
  "name": "paymentDetailsReady",
  "payload": {
    "vendorId": "00902TZVGLSIDHF1m603",
    "paymentId": "stp02WATPBNYIEC206dd"
  }
}

`schedulePaymentReady`

The schedulePaymentReady event is emitted when the Element is rendered successfully.

// Empty payload
{
  "name": "schedulePaymentReady",
  "payload": {}
}

`mfaReady`

The mfaReady event is emitted when the Element is rendered successfully. When the signed-in user session is MFA-trusted, the returned setup value is true. When the session is not MFA-trusted, the returned required value is true.

{
  setup: boolean;
  required: boolean;
}

`userVerificationReady`

The userVerificationReady event is emitted when the Element is rendered successfully. If user verification is required, the returned required value is true.

{
  required: boolean;
}

`cancelPaymentReady`

The cancelPaymentReady event is emitted when the cancel payment modal on the Payment Details page is rendered successfully.

{
  "name": "cancelPaymentReady",
  "payload": {
    "vendorId": "00902BVDJRYKUHO1ml7w",
    "paymentId": "stp02BKJJVVCMDY1vl8s"
  }
}

`voidPaymentReady`

The voidPaymentReady event is emitted when the void payment modal on the Payment Details page is rendered successfully.

{
  "name": "voidPaymentReady",
  "payload": {
    "vendorId": "00902BVDJRYKUHO1ml7w",
    "paymentId": "stp02BKJJVVCMDY1vl8s"
  }
}

Selected events

The Selected events fire when the user clicks a link or an interactive element. See Initialize the Element experience for navigation details and your response options.

`paymentsListSchedulePaymentSelected`

The paymentsListSchedulePaymentSelected event is emitted when the user clicks Schedule payment on the Payments List page. The Element handles the subsequent navigation.

// Empty payload
{
  "name": "paymentsListSchedulePaymentSelected",
  "payload": {}
}

`paymentsListPaymentDetailsSelected`

The paymentsListPaymentDetailsSelected event is emitted when the user clicks Payment Details on the Payments List page. The Element handles the subsequent navigation.

{
  "name": "paymentsListPaymentDetailsSelected",
  "payload": {
    "vendorId": "00902BVDJRYKUHO1ml7w",
    "paymentId": "stp02BKJJVVCMDY1vl8s"
  }
}

`paymentsListVendorDetailsSelected`

The paymentsListVendorDetailsSelected event is emitted when the vendor name is clicked on the Payment List page.

{
  "name": "paymentsListVendorDetailsSelected",
  "payload": {
    "vendorId": "00902BVDJRYKUHO1ml7w"
  }
}

`paymentListVendorSetupSelected`

The paymentListVendorSetupSelected event is emitted when the user clicks Add Vendor on the Payment List page.

// Empty payload
{
  "name": "paymentListVendorSetupSelected",
  "payload": {}
}

`paymentListAddFundingSelected`

The paymentListAddFundingSelected event is emitted when the user clicks Set up an active funding method on the Payment List.

// Empty payload
{
  "name": "paymentListAddFundingSelected",
  "payload": {}
}

`paymentDetailsVendorDetailsSelected`

The paymentDetailsVendorDetailsSelected event is emitted when the user clicks Vendor Name on the Payment Details page.

{
  "name": "paymentDetailsVendorDetailsSelected",
  "payload": {
    "vendorId": "00902BVDJRYKUHO1ml7w"
  }
}

`schedulePaymentVendorSetupSelected`

The schedulePaymentVendorSetupSelected event is emitted when the user clicks Add a new vendor.

{
  "name": "schedulePaymentVendorSetupSelected"
}

`schedulePaymentVerifyDepositSelected`

The schedulePaymentVerifyDepositSelected event is emitted when the user clicks Verify Deposit to begin trial deposit verification. The Element handles the subsequent navigation.

{
  "name": "schedulePaymentVerifyDepositSelected"
}

`schedulePaymentUserVerificationSelected`

The schedulePaymentUserVerificationSelected event is emitted when the user clicks Verify Identity to complete a required identity verification. The Element handles the subsequent navigation.

{
  "name": "schedulePaymentUserVerificationSelected"
}

`cancelPaymentSelected`

The cancelPaymentSelected event is emitted when the user clicks Cancel Payment on the Payment Details page. The Element handles the subsequent navigation.

"name": "cancelPaymentSelected",
  "payload": {
    "vendorId": "00902BVDJRYKUHO1ml7w",
    "paymentId": "stp02BKJJVVCMDY1vl8s"
  }
}

`voidPaymentSelected`

The voidPaymentSelected event is emitted when the user clicks Void Payment on the Payment Details page. The Element handles the subsequent navigation.

"name": "voidPaymentSelected",
  "payload": {
    "vendorId": "00902BVDJRYKUHO1ml7w",
    "paymentId": "stp02BKJJVVCMDY1vl8s"
  }
}

Success events

The Success events fire when the user-initiated action completes successfully.

`schedulePaymentSuccess`

The schedulePaymentSuccess event is emitted when the payment is scheduled successfully.

{
  "name": "schedulePaymentSuccess",
  "payload": {
    "vendorId": "00902TZVGLSIDHF1m603",
    "paymentId": "stp02NMYWTABIXT21094",
    "amount": 2.22,
    "paymentType": "Check"
  }
}

`mfaSuccess`

The mfaSuccess event is emitted when the MFA setup or MFA challenge is submitted successfully. Note that rememberMeId is available in the payload only when MFA rememberMe is set as true for the user.

{
  setup: boolean;
  required: boolean;
  rememberMe?: boolean;
  rememberMeId: string;
  deviceId: string;
}

`userVerificationSuccess`

The userVerificationSuccess event is emitted when the user completes the verification flow with the User verification Element. When this event is fired, this is a signal for the event listener that the user has completed the flow in the Element, and it is safe to route the user.

Verification result	Description
`Approved`	User verification is complete and the user is approved
`In_Review`	User verification is in review

{
  userId: string;
  verificationResult: 'Approved' | 'In_Review' | 'Not_Applicable';
}

`cancelPaymentSuccess`

The cancelPaymentSuccess event is emitted when the user completes the cancel payment flow. The payload indicates if the cancellation request was submitted.

{
  "name": "cancelPaymentSuccess",
  "payload": {
    "paymentId": "stp02BKJJVVCMDY1vl8s",
    "vendorId": "00902BVDJRYKUHO1ml7w",
    "paymentCanceled": true
  }
}

`voidPaymentSuccess`

The voidPaymentSuccess event is emitted when the user completes the void payment flow. The payload indicates if the void request was submitted.

{
  "name": "voidPaymentSuccess",
  "payload": {
    "vendorId": "00902ZMQSNWRJUO1g10q",
    "paymentId": "stp02BXTCHMVMVE20nsg",
    "paymentVoidRequested": false
  }
}

Error handling

`error`

The error event is emitted when an error occurs during the use of the Payments Element. For this Element, there is 1 possible error event. In all other error cases, error message banners are displayed in the Element.

Event	Description
`WIDGET_INTERNAL_ERROR`	HTTP 500 internal server error

BILL follows a pattern for all errors.

Pattern
BILL emits a standardized and singular `error` event for all Elements. All the error payloads follow a consistent and predictable shape.
BILL emits `error` events only when the user cannot recover from an error in the BILL experience. This should occur only when the requirements for launching an Element are not met. Errors are emitted immediately for you to respond and close the BILL experience.
If your application does not handle the BILL error events, BILL provides a fallback experience for the user. This experience does not have any interactive element that your application is required to respond to. When the user lands on the fallback experience, BILL recommends that you either navigate the user correctly or add interactive elements to enable the user to close the Element.