Payment Requests

A payment request is a payee asking you to pay them: a reimbursement with receipts, or an invoice. The payee writes and submits it from the payee portal or the payee widget; you review it and decide. Approving and paying turns requests into ordinary payout payments, so everything in Payouts applies to the money once it moves.

Before you start

• Payment requests are enabled per account by Payment Labs.
• Every operation on this page needs the Payment Requests permission. See Access to wallets and payment requests.
• To pay requests you need a ledger account (see Funding and Ledger Accounts) and, optionally, a batch to pay into.

Request statuses

A request also lists the payments raised for it in payments, each with its paymentStatus, which follows the payment through its statuses.

Payment Labs sends no webhook when a payee submits or changes a request. Search the queue on a schedule to find new requests. Once you pay a request, its payment sends the usual payment webhooks.

Step 1: Find requests waiting for you

Search the queue with Search Payment Requests:

{
  "filter": { "all": [{ "fact": "status", "operator": "equals", "value": "PENDING_APPROVAL" }] },
  "sort": [{ "fieldName": "submittedAt", "order": "asc" }],
  "page": 1,
  "pageSize": 50
}

You can filter and sort on the request's ID, type (REIMBURSEMENT or INVOICE), status, title, amount, currencyCode, invoice fields, requester.*, payments.*, and its dates. Search results can be a few seconds behind.

To page through every request instead, use List Received Payment Requests with limit (1 to 100, default 50) and pass the response's nextCursor as cursor for the next page.

Step 2: Read the request before you decide

Search is right for a list but wrong for a decision: the payee may have changed the request since it was indexed. Read it with Get Received Payment Request before you approve.

Each attached document is read automatically. extractionStatus on the attachment says whether reading is PENDING, COMPLETED or FAILED. Fields the reading was unsure of and the payee has not confirmed are listed in fieldsNeedingConfirmation (lines carry needsConfirmation), lineItemsDiscrepancy flags lines that do not add up to the document's total, and overrides shows every value the payee changed beside what was read.

To open an attached receipt or invoice, call Get Received Payment Request Attachment URL. It returns a previewUrl (to show in a browser), a downloadUrl, the fileName and an expiresAt. The links are short-lived; request new ones when they expire.

Step 3: Decide

You have three options. Each takes 1 to 50 requests per call except Reject, which takes one.

Reject

Reject Payment Request with a reason the payee will read:

{ "reason": "The receipt for the hotel night is missing. Please attach it and resubmit." }

The request moves to NOT_APPROVED. Only a PENDING_APPROVAL request can be rejected.

Approve without paying

Approve Payment Requests records the decision only. No batch, ledger account or payment is involved. Use it when approval and payment are separate steps for you.

{ "requestIds": ["PR-01JDB1C2D3E4F5G6H7J8K9M0N1", "PR-01JDB1C2D3E4F5G6H7J8K9M0N2"] }

Approve and pay

Approve Payment Requests and Pay approves the requests and raises their payments in one call. It accepts requests that are PENDING_APPROVAL or already APPROVED.

{
  "requestIds": ["PR-01JDB1C2D3E4F5G6H7J8K9M0N1", "PR-01JDB1C2D3E4F5G6H7J8K9M0N2"],
  "batch": { "name": "October reimbursements", "defaultPaymentCategory": "reimbursement" },
  "ledgerAccount": "A-01JD8ZK3V6M2Q4R7T9W1X3Y5Z7",
  "sendImmediately": true
}

How it behaves:

• One payment per payee. Several requests for the same payee are paid as one payment and share a paymentId. createdCount counts requests; createdPaymentCount counts payments.
• Retries are safe. Calling again with the same requests lands on the same payments; it never pays twice.
• A row can finish later. A row with reservedPaymentId and no paymentId is still having its payment created; queuedReason says why (BUDGET: the call ran out of time, TRANSIENT: a temporary error, retried automatically). Treat it as approved and not yet paid, and read the request later.

Read the results

Approve and Approve and Pay return 200 even when some requests were refused. Check every row in results:

{
  "total": 2,
  "approvedCount": 1,
  "failedCount": 1,
  "results": [
    { "requestId": "PR-01JDB1C2D3E4F5G6H7J8K9M0N1", "approved": true, "status": "APPROVED", "batchId": "B-01JDB2D3E4F5G6H7J8K9M0N1P2", "paymentId": "P-01JDB3E4F5G6H7J8K9M0N1P2Q3" },
    { "requestId": "PR-01JDB1C2D3E4F5G6H7J8K9M0N2", "approved": false, "errorCode": "NOT_AWAITING_DECISION" }
  ],
  "batchId": "B-01JDB2D3E4F5G6H7J8K9M0N1P2",
  "batchCreated": true,
  "createdCount": 1,
  "createdPaymentCount": 1,
  "queuedCount": 0,
  "queuedPaymentCount": 0
}

Errors and edge cases

Next steps

• Payment Statuses
• Creating and Submitting Payments