title: Bill Payments source_url: /developer-api/v1/bill-payments summary: Create approved bills via the API, attach documents, choose a payment method, and pay vendors end-to-end — without forcing your AP team to leave your stack. content: Create approved bills via the API, attach documents, choose a payment method, and pay vendors end-to-end — without forcing your AP team to leave your stack. An integration that creates and pays bills programmatically. By the end you'll have: A working POST /bills request that resolves every required UUID upfront. A payment method selected per bill — card (cashback), ACH, check, wire, SWIFT, or stablecoin — with the right shape for each. Invoice and supporting documents attached to the bill. Optional 3-way match against an upstream purchase order and item receipt. Estimated time: 1–2 hours for a working integration. Prerequisite knowledge: OAuth on Ramp, the Bill Pay mental model, and how Vendors relate to Merchants and Accounting Vendors (see Data relationships). Required scopes: bills:write to create bills; bills:read to read; entities:read and vendors:read to resolve UUIDs. Required configuration: Bill Pay must be enabled for your organization. Verify by calling GET /entities and confirming a bank account with usage_type = BILL_PAY_BANK_ACCOUNT is present. If it isn't, follow the Bill Pay set-up guide in the dashboard, then retry. Recommended: Read Bill Pay for the bill lifecycle and Spend Controls for how approvals gate bills. A bill created via the API skips the draft phase and lands in Approved. From there, Ramp processes the payment using the method you chose; the bill moves to Paid once the payment clears. Webhooks fire at each transition. Bills created via API are auto-approved. If your customer's policy requires human approval before payment, use the draft-bill endpoints instead — but draft bills can only be approved through the Ramp dashboard, not the API. Implementation POST /bills requires several IDs. Fetch them from the endpoints below and reuse them across bills wherever possible. Source endpoint Response field Request field on POST /bills GET /entities id entity_id bank_accounts[].id where usage_type = BILL_PAY_BANK_ACCOUNT source_bank_account_id GET /vendors vendor_id GET /vendors/{id}/contacts vendor_contact_id GET /vendors/{id}/accounts id (ACH / wire / SWIFT / stablecoin only) vendor_account_id Missing BILL_PAY_BANK_ACCOUNT? If you don't see a bank account with usage_type = BILL_PAY_BANK_ACCOUNT in your GET /entities response, Bill Pay isn't enabled for your organization yet. Follow the Bill Pay set-up guide to configure it, then retry your API call. Verify: every UUID you'll need for the next step is in hand and points at an active object. Six payment methods. Each carries a different shape on POST /bills. Card — pay by Ramp card. Earns cashback. Two card options: Existing Ramp card — use an already-issued card. Share card details with the vendor manually, then rely on Ramp's automatic transaction matching to link the payment to the bill once it clears. Single-use virtual card — Ramp generates a unique virtual card per bill, with the limit set to the bill amount. Two delivery options: Card delivery disabled — card details become available once the bill is approved; share with the vendor manually. Card delivery enabled — Ramp emails the vendor's primary contact on the due date, with reminders at 2, 4, and 7 days. Card delivery disabled — card details become available once the bill is approved; share with the vendor manually. Card delivery enabled — Ramp emails the vendor's primary contact on the due date, with reminders at 2, 4, and 7 days. Single-use cards auto-lock when the spending limit is reached, after 14 days (delivery enabled) or 21 days (delivery disabled). Transaction matching happens automatically once payments clear. Supports international bills in local currency. For programmatic access to full card details (PAN/CVV), see Virtual cards. To filter out one-time card transactions in the Transactions API, set has_no_sync_commit=true. ACH, check, wire, SWIFT, and stablecoin — all require a source_bank_account_id from GET /entities. Method Requirements Timing ACH Verified vendor bank account 2–3 business days Check Vendor address 5–7 business days Wire Same-day (domestic) SWIFT Varies (international) Stablecoin Vendor crypto wallet Minutes (on-chain) Payments arrive by payment_arrival_date (cannot be a weekend or bank holiday). Non-check payments require a verified vendor bank account via GET /vendors/{id}/accounts. Check payments require a vendor address on file. Expedited ACH and wire payments are not available via API. Pick a method below and the builder will assemble the POST /bills request for it — card bills nest a different sub-object than ACH bills, so the shape changes per method. Upload invoice PDFs or supporting documents using POST /bills/{bill_id}/attachments. The endpoint accepts multipart/form-data. POST /developer/v1/bills/{bill_id}/attachments Upload an invoice or supporting document (multipart/form-data). Shape callout: Verify: GET /bills/{bill_id} returns the attachment in the bill's attachments array. If the bill comes from an approved purchase order, verify a 3-way match — bill, PO, and item receipt all reference the same line items. Get the bill → extract purchase_order_ids, line_items[].purchase_order_line_item_id, and inventory_line_items[].purchase_order_line_item_id. Get the purchase order → extract item_receipt_ids. Get the item receipt → confirm line_items[].purchase_order_line_item_id matches the bill. When all three documents share the same line-item IDs, you have a verified match. See Procurement Intake for the upstream of how POs come to exist. Subscribe to bill webhooks. Listen for bills.created, bills.approved, bills.paid, and bills.rejected to drive status in your UI without polling. See Webhooks. Idempotency on retries. Pass an idempotency_key on POST /bills so a retry doesn't double-create a bill (or double-pay a vendor). Validate up front, not on submit. Check that the vendor has the right account type (ACH requires vendor_account_id; check requires an address) before assembling the request. Ramp returns clear 400s on submission, but failing fast in your UI is friendlier. Mind the API limitations. Bills created via API are auto-approved; approval-workflow gating happens in Ramp, not via API. Payments are nested in bills and have limited update support once created. Batch payments (one payment across multiple bills) aren't supported. Sync to ERP. Bills sync automatically with direct accounting connections (QuickBooks, NetSuite, etc.). For custom integrations, use the sync_status model — see ERP Integrations. UCSV restriction Bills cannot be synced via API with Universal CSV. Use the dashboard export instead. ERP Integrations — sync bills and payments to your accounting system after they clear. Procurement Intake — bills produced downstream of an approved procurement request. Bill Pay — the Product hub for bills. Data relationships — how the bill-pay Vendor relates to card Merchants and ERP Accounting Vendors. Cards — pay bills with a Ramp card for cashback. Spend Controls — the approval policy that gates bills. Bills — create, list, fetch, update, and archive bills. Includes nested payment details. Bank Accounts — verified funding sources for bill payment. Transfers — wire-transfer payment objects, including bill-related transfers. Vendors — bill-pay payees, contacts, bank accounts. Entities — legal entities and their bill-pay bank accounts. Webhooks — subscribe to bills.* events. Pagination — paginate GET /bills. Authorization — bills:read / bills:write scopes.