Create Virtual Payment

post

https://api-sandbox.paymentlabs.io/batches/{batchId}/virtual-payments

Creates a virtual payment: a payment that records an amount owed to a payee and books its tax withholdings, without paying
the payee.

Use it when you hold the payee's balance yourself, for example in your own in-app wallet, and need tax withholdings and
reporting to follow each credit. When the payee later withdraws, create and submit a regular payment with Create Payment.

Requires the Write permission. The body, payee matching, defaults, errors and the duplicate warning are the same as
Create Payment.

A virtual payment has the same statuses as a regular payment and you manage it with the same operations, using its ID in the
/batches/{batchId}/payments/{paymentId} paths: Get Payment, Update Payment, Cancel Payment, Submit Payment. When you submit
it:

The payee must be payable, as for a regular payment.
Your ledger account balance must cover the full sourceAmount, otherwise 423 INSUFFICIENT_BALANCE.
Only the tax withholdings and fees leave your ledger account. No payout method is used and nothing reaches the payee.
Status webhooks fire only when the payment reaches COMPLETED.

virtualPayment is true on the returned payment.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

batchId

string

required

ID of the batch, as returned by Create Batch.

Body Params

Body of Create Payment and Create Virtual Payment.

referenceId

string

Your own identifier for this payment, such as the payout ID in your system. Free text. It is not unique: Payment Labs accepts a
second payment with the same value, so it does not protect you from duplicates.

payeeEmail

string

Email of the payee. Send it, payeeReferenceId, or both; see the endpoint description for how the payee is matched or
created.

payeeReferenceId

string

Your own identifier for the payee, such as the user ID in your system. Unique per payee within your account. When you create a
new payee by email without it, the payee's reference ID is set to their email address. See /docs/payee-reference-ids.

sourceAmount

string

required

Amount to pay, as a decimal string in the currency of the ledger account ("125.50"). Send an amount greater than zero: a
zero amount is accepted but the payment can never be submitted.

ledgerAccount

string

Ledger account the money is paid from, by ID or alias. The payment is in that account's currency. Optional when your account
has a single active ledger account; required when it has several. List your accounts with List Ledger Accounts.

paymentCategory

string

enum

Category of the payment. It decides the tax treatment together with taxJurisdiction. Defaults to the batch's defaultPaymentCategory.

taxJurisdiction

string

enum

Tax jurisdiction whose rules apply to this payment. Must be one enabled on your account, or none. Defaults to the batch's jurisdiction.

payeeMemo

string

Message shown to the payee with the payment. Defaults to the batch name.

payorMemo

string

Note for your own records. Payment Labs screens do not show it to the payee. Do not put secrets in it.

201The virtual payment was created in DRAFT.

404The resource does not exist in your account.

422The request body is not valid JSON, or is not a JSON object. Send Content-Type: application/json with a JSON object body.

423The resource is in a state that does not allow this change, for example a payment that has already been submitted or a batch that has been archived. Read the resource again to see its current state.