BILL AP Virtual Card payment workflow

With BILL AP payments, waiting for traditional check or ACH delivery is not always an option. Whether you are paying a last-minute utility bill or an urgent vendor payment, BILL virtual cards offer a fast and secure disbursement method. Instead of waiting for physical mail, BILL sends the vendor a single-use, 16-digit Mastercard or Visa number to process immediately.

In this recipe

In this recipe, you build an API workflow that enables you to check whether a vendor accepts virtual cards as a payment method, and pay the vendor with an AP virtual card.

What you'll build

In this recipe, you create an integration with the BILL API in the sandbox environment.

Pay a domestic vendor (US vendor) that accepts virtual cards.
Pay an international vendor (outside US) that accepts virtual cards.

Note: In this recipe, you pay a domestic vendor with the bill currency set to USD. If a vendor does not process the virtual card within 20 days, the card expires and becomes void. When this happens, BILL automatically reissues the payment as a check or ACH, depending on how the vendor preferred to be paid previously.

What you need before you begin

Prerequisite	Description
API basics	A basic understanding of working with API endpoints.
Credentials	Your credentials are required for you to build with the BILL AP & AR API. If you have not set up your credentials, sign up to create your sandbox BILL account. When you sign up, you create a test BILL organization, and you generate your username, password, organization ID, and developer key. See Sandbox API sign up for detailed steps.
MFA setup	Your MFA setup must be complete. BILL requires MFA for creating payments with the API. MFA at BILL requires a one-time setup. When you sign up with the BILL web app to generate your credentials, you complete 2-step verification/MFA with a valid phone number.
Test bank account	A test bank account added in your BILL organization. You use this test bank account to create a test payment in this recipe. See Sandbox API bank account setup for detailed steps.

Chapter 1: API login

In this chapter, you log in to your BILL account with the API.

To begin, enter your API login credentials in the fields below. See the What you need before you begin section in this recipe if you have not set up your credentials.

Sandbox base URLhttps://gateway.stage.bill.com/connect

Production base URLhttps://gateway.prod.bill.com/connect

Complete your API login with the required credentials. Simply click Send to get a 200 OK response.

post/v3/loginAPI login

Base URL

Body * required

Required: username, password, organizationId, devKey

username*

password*

organizationId*

devKey*

{
  "username": "{{username}}",
  "password": "{{password}}",
  "organizationId": "{{organization_id}}",
  "devKey": "{{developer_key}}"
}

In the response, a new sessionId is available. You use this sessionId and your devKey in all subsequent BILL API requests. A 200 OK response confirms that you are a signed-in user. The sessionId expires after 35 minutes of inactivity. At that point, you are automatically signed out, and you must sign in again with the API login endpoint and generate a new sessionId.

Note that the trusted field in the response is set as false. When the API login session is MFA-trusted, the trusted field is set as true. We enable MFA in this API session in Chapter 2.

Chapter 2: MFA

In this chapter, you step up your current API session as MFA-trusted. BILL requires MFA for creating payments with the API. In the next set of steps, you first generate an MFA challenge, validate the MFA challenge, and then step up the API login session as MFA-trusted.

Step 1: Generate MFA challenge

Generate an MFA challenge ID with POST /v3/mfa/challenge. Click Send. You receive a 6-digit token sent to your phone number.

post/v3/mfa/challengeGenerate MFA challenge

Headers

sessionId

devKey

In the response, a challengeId is available. You use this value in Step 2.

Step 2: Validate MFA challenge

Validate the MFA challenge with POST /v3/mfa/challenge/validate. In the request, set the required fields, and then click Send.

Set token as the 6-digit token sent to your phone number.
Set device and machineName as a test device name — for example, test-device. Device name is required in the next step.

post/v3/mfa/challenge/validateValidate MFA challenge

Headers

sessionId

devKey

Body * required

Required: challengeId, token, device, rememberMe

challengeId*

token*

device*

machineName

{
  "challengeId": "{{mfa_challenge_id}}",
  "token": "{{mfa_token}}",
  "device": "{{device}}",
  "machineName": "{{machine_name}}",
  "rememberMe": true
}

In the response, a rememberMeId is available. You use this value in Step 3.

Step 3: Step-up API session as MFA-trusted

Step up your API session as MFA-trusted with POST /v3/mfa/step-up. Set device to the device name used in Step 2, and then click Send. Your current API session is now MFA-trusted.

post/v3/mfa/step-upMFA step-up for API session

Headers

sessionId

devKey

Body * required

Required: rememberMeId, device. device is auto-filled from Step 2.

rememberMeId*

device*

{
  "rememberMeId": "{{mfa_remember_me_id}}",
  "device": "{{device}}"
}

In the response, trusted is set as true. Your API session is now MFA-trusted.

Chapter 3: Get list of vendors

In this chapter, you get a list of vendors in your BILL organization.

To create a payment, you first need the BILL-generated id of a vendor. When you get a list of vendors with GET /v3/vendors, you get the details of vendors in your BILL organization.

The ?status=ENROLLED query parameter enables you to list vendors that are enrolled to accept virtual cards as a payment method.

Click Send to get the list of vendors.

get/v3/vendors?status=ENROLLEDGet list of vendors

Headers

sessionId

devKey

In the response, a BILL-generated vendor id is available. In addition, payByType is set as VIRTUAL_CARD to state the vendor payment method.

You can sign in to the BILL web app to view this vendor record in your BILL organization. To view a list of vendors that accept virtual cards in your BILL organization, see Verify vendors accept virtual cards in the BILL Help Center.

In Chapter 4, you use the vendor id to create a payment for the virtual card vendor.

Chapter 4: Create a virtual card payment

In this chapter, you create a virtual card payment in your BILL organization.

When you create a payment with POST /v3/payments, a payment record is created in your BILL organization.

Click Body below to view an example body for the Create a virtual card payment API request. In the request, vendorId is set to the id of the vendor (from Chapter 3). In addition, the fundingAccount is set as AP_CARD and the processDate is set to a valid US business day. Finally, createBill is set to true and a billId value is not set. With this configuration, you are telling BILL to auto-generate a bill when the payment API request is submitted.

Click Send to create a new payment.

post/v3/paymentsCreate a payment

Headers

sessionId

devKey

Body * required

Required: vendorId, processDate, fundingAccount.type, amount

vendorId*

processDate*

fundingAccount.type*

amount*

requestPayFaster

createBill

{
  "vendorId": "{{vendor_id}}",
  "processDate": "2026-12-31",
  "fundingAccount": {
    "type": "AP_CARD"
  },
  "amount": 200,
  "processingOptions": {
    "requestPayFaster": false,
    "createBill": true
  }
}

A 201 Created response confirms that the virtual card payment was successfully created.

You just paid a domestic virtual card vendor. In the response, a BILL-generated payment id is available for the paid bill.

The disbursementType is set as VIRTUAL_CARD, which is a BILL disbursement method where BILL sends the vendor a single-use, 16-digit Mastercard or Visa number. When BILL starts processing this payment, an additional disbursementInfo object is also available in the response.

Finally, singleStatus provides updates at different stages in a BILL payment lifecycle. The values are based on payment status and disbursementStatus. See Single status payment values for the complete list of status values.

You can sign in to the BILL web app to view this payment in your BILL organization. An email is also sent to your email address about the scheduled payment.

What you learned in this recipe

You just created AP payments for domestic vendors with the BILL v3 API. You learned a lot along the way.

Create an API session and perform MFA step-up.
Get a list of vendors enrolled to accept virtual cards.
Create a payment with an AP card.