Vendor Payments

Vendor payments represent outbound payment execution from the partner to vendors. In the Accounts Receivable API, payments flow from customers to the partner. In Accounts Payable, payments flow from the partner to vendors.

Endpoints

Method	Path	Description
POST	/vendor-payments	Initiate payment for one or more bills
POST	/vendor-payments/cancel	Cancel a single vendor payment
POST	/vendor-payments/bulk-cancel	Cancel multiple vendor payments
POST	/vendor-payments/{bill_id}/retry	Retry a failed payment

---

Pay Date Prerequisite

A bill must have a pay_date set before a vendor payment can be initiated. If pay_date is null, the payment request will return 422 Unprocessable Entity.

Use POST /bills/{id}/pay-date to set it first:

POST /bills/{id}/pay-date
{
  "pay_date": "2026-04-15"
}

Then create the vendor payment.

---

Create Vendor Payment

POST /vendor-payments

Initiates payment for one or more bills. Each item specifies the bill, payment method, and optional payment speed.

Request Body

{
  "items": [
    {
      "bill_id": "660e8400-e29b-41d4-a716-446655440000",
      "payment_method_id": "770e8400-e29b-41d4-a716-446655440000",
      "payment_speed": "standard"
    }
  ],
  "idempotency_key": "880e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Required	Description
items	array	Yes	One or more payment items
items[].bill_id	string (UUID)	Yes	Bill to pay
items[].payment_method_id	string (UUID)	Yes	Payment method to use
items[].payment_speed	enum	No	standard (default), next_day, same_day, instant. Invalid values return 400.
idempotency_key	string	No	Idempotency key for the request

Response (200 OK)

{
  "results": [
    {
      "bill_id": "660e8400-e29b-41d4-a716-446655440000",
      "success": true
    }
  ]
}

---

Cancel Vendor Payment

POST /vendor-payments/cancel

Cancels a single vendor payment that has not yet been sent.

Request Body

{
  "bill_id": "660e8400-e29b-41d4-a716-446655440000",
  "payment_id": "990e8400-e29b-41d4-a716-446655440000"
}

Response (200 OK)

{
  "payment_id": "990e8400-e29b-41d4-a716-446655440000",
  "status": "canceled"
}

---

Bulk Cancel Vendor Payments

POST /vendor-payments/bulk-cancel

Cancel multiple vendor payments in a single request.

Request Body

{
  "items": [
    {
      "bill_id": "660e8400-e29b-41d4-a716-446655440001",
      "payment_id": "990e8400-e29b-41d4-a716-446655440001"
    },
    {
      "bill_id": "660e8400-e29b-41d4-a716-446655440002",
      "payment_id": "990e8400-e29b-41d4-a716-446655440002"
    }
  ]
}

Response (200 OK)

{
  "results": [
    { "bill_id": "660e8400-...-440001", "success": true },
    { "bill_id": "660e8400-...-440002", "success": true }
  ]
}

---

Retry Failed Payment

POST /vendor-payments/{bill_id}/retry

Retries the last failed funding attempt for a bill. No request body required.

Response (200 OK)

{
  "bill_id": "660e8400-e29b-41d4-a716-446655440000"
}

---

Payment Speeds

Speed	Description
standard	Standard ACH (2-3 business days)
next_day	Next business day delivery
same_day	Same-day ACH
instant	Real-time payment

Vendor Payment Statuses

Status	Description
hold	Payment is on hold
waiting_pay_date	Waiting for the scheduled pay date
ready	Ready to be processed
processing	Payment is being processed
succeeded	Payment completed successfully
failed	Payment failed

Vendor Payment Object (within Bill response)

When retrieving a bill, vendor payments are included in the vendor_payments array:

{
  "id": "990e8400-e29b-41d4-a716-446655440000",
  "attempt_number": 1,
  "status": "processing",
  "hold_until": "2026-04-04T00:00:00Z",
  "sent_at": null,
  "failure_reason": null,
  "payment_method_id": "770e8400-e29b-41d4-a716-446655440000",
  "estimated_arrival_date": "2026-04-07T00:00:00Z",
  "payment_speed": "standard"
}