Create Payment

post

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

Creates a payment for one payee in a batch. The payment starts as DRAFT; nothing is paid until you submit it.

Requires the Write permission.

Payee. Identify the payee with payeeEmail, payeeReferenceId, or both. Payment Labs finds the payee or creates one:

You send	Result
`payeeReferenceId` only	The payee with that reference ID. `400 REFERENCE_ID_NOT_FOUND` if there is none.
`payeeEmail` only	The payee with that email, or a new payee whose reference ID is the email.
Both, reference ID known	That payee. If the email differs, the payee's email is changed to the one you sent. `400 EMAIL_ALREADY_IN_USE` if another payee already uses that email.
Both, only the email known	That payee. Its reference ID is changed to the one you sent.
Both, neither known	A new payee with that email and reference ID.

See /docs/payee-reference-ids before you send both.

Defaults. paymentCategory, taxJurisdiction and payeeMemo default to the batch's category, jurisdiction and name.
ledgerAccount can be omitted when you have a single active ledger account. The payment's currency is the ledger account's currency.

Side effects. The payee receives an email: an invitation to sign up if they are new, otherwise a notice of the payment.
The payment-created webhook fires. A service fee is charged for the payment shortly after creation and shows in
chargedServiceFee; it is refunded if you cancel within the grace period.

Duplicates. This operation is not idempotent and referenceId is not unique. A retried request creates a second payment
and emails the payee again. If a request times out, search for your referenceId with Search Payments before retrying.

Errors

400 VALIDATION_ERROR with details.ledgerAccount[0].code = MORE_THAN_ONE_LEDGER_ACCOUNT: you have several ledger accounts; send ledgerAccount. constraints.validAccounts lists their aliases.
400 VALIDATION_ERROR with details.ledgerAccount[0].code = INVALID_LEDGER_ACCOUNT: no active ledger account has that ID or alias.
400 VALIDATION_ERROR on tags: tags are not enabled on your account, or a tag breaks your limits.
400 REQUIRED_VALUES_MISSING: send payeeEmail, payeeReferenceId, or both.
400 REFERENCE_ID_NOT_FOUND: no payee has that reference ID; add payeeEmail to create one.
400 EMAIL_ALREADY_IN_USE: the email belongs to a different payee than the reference ID.
404 NOT_FOUND: the batch does not exist.
423 NOT_EDITABLE: the batch is archived or does not accept payments.

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 payment was created in DRAFT. The Location header holds its path.

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.