Sent when a payment is added to one of your batches.
payment-created tells you that a new payment exists in one of your batches.
When it fires
- Once for every new payment, however it was created: Create Payment, Create Virtual Payment, a file import, an approved payment request, or the dashboard.
- Also when Payment Labs creates a payment for you, for example the payment that reverses a tax withholding.
The payment usually arrives in DRAFT. It arrives in RESTRICTED when the payee's country is blocked for the batch. Because the payload is read when the webhook is sent, the payment may already have moved on, for example to SUBMITTED.
What to do
- Store the payment
idnext to yourreferenceId, so later events for this payment find your record. - Do not treat this event as a payout. Money moves only after you submit the payment. Track that with payment-status-changed.
Payload
data is the payment as Get Payment describes it, read when the webhook is sent. Fields with no value are omitted. Amounts use the Money object.
| Field | Type | Description |
|---|---|---|
id | string | Payment ID, for example P-01JC8Z4M6Q2W3E4R5T6Y7U8I9O. |
batchId | string | ID of the batch that holds the payment. |
batchName | string | Name of that batch. |
referenceId | string | Your own reference for this payment. Use it to match the payment to a record in your system. |
status | string | Current status of the payment. See Payment statuses. |
submitted | boolean | true once the payment has been submitted for processing. |
completed | boolean | true once the payment has been paid. |
sourceAmount | Money | Amount you pay, in the payment's source currency. |
destinationAmount | Money | Amount the payee receives, in the payee's currency. Set once the conversion is known. |
refundAmount | Money | Amount returned to your ledger account after the payout came back. Set when status is RETURNED. |
ledgerAccount | string | ID of the ledger account that funds the payment. |
payeeMemo | string | Message shown to the payee with the payment. |
payorMemo | string | Internal note for your team. The payee does not see it. |
paymentCategory | string | What the payment is for. Drives tax treatment. One of online-esport-prize, in-person-esport-prize, in-person-esport-prize-out-of-jurisdiction, athlete-prize, online-misc-prize, online-contest-prize, in-person-misc-prize, in-person-contest-prize, remote-contractors, in-person-contractors, reimbursement, royalties. |
taxJurisdiction | string | Tax rules applied to the payment: us, de, fi, gb, my, pl, sa, se, or none. |
chargedServiceFee | Money | Service fee charged for this payment, in USD. |
refundedServiceFee | Money | Part of the service fee given back, in USD, for example after a cancellation. |
isServiceFeeRefundable | boolean | true if cancelling the payment now would return the service fee. |
cancellationReason | string | Why the payment was cancelled or expired. Set when status is CANCELLED or EXPIRED. |
virtualPayment | boolean | true for a virtual payment, which books fees and tax withholdings without sending money to the payee. |
isEditable | boolean | true if you can still change the payment with Update Payment. |
isCancellable | boolean | true if you can still cancel the payment with Cancel Payment. |
isSubmittable | boolean | true if you can submit the payment now: it can be submitted and the payee is payable. |
isAutoSubmittable | boolean | true if the payment can be submitted automatically later, once the payee becomes payable. |
isAutoSubmitOn | boolean | true if the payment is set to submit automatically once the payee becomes payable. |
allowedPaymentMethods | string[] | Payout methods the payee may use for this payment, for example bank-transfer-1 or paypal. Absent when every method enabled for your account is allowed. |
lastActivity | string | Date and time of the latest activity on the payment (submission, or else the last update), in ISO 8601 UTC. |
tags | object[] | Tags on the payment. Each has a key (string) and a value (string or array of strings). |
tagKeys | string[] | The keys of tags, for filtering. |
payee | object | The payee being paid. See the table below. |
payablePayee | object | The same object as payee, kept for older integrations. Read payee instead. |
auditInfo | object | Timestamps and authors. See the table below. |
payee object:
| Field | Type | Description |
|---|---|---|
id | string | Payee ID, the same value as userId. |
userId | string | Payee ID. |
payorId | string | Your payor ID. |
referenceId | string | Your reference for the payee. |
email | string | Payee's email address. |
payable | boolean | true if the payee had completed onboarding and could be paid when the payment was last updated. Subscribe to payee-payability-changed for the live value. |
currentStep | string | Onboarding step the payee must finish next: identityVerification, personalInformation, paymentMethods, or taxForms. Absent once onboarding is complete. |
onboarded | boolean | true if the payee's personal information had been accepted when the payment was last updated. It does not cover payout methods or tax forms: use payable to know whether the payee could be paid. |
auditInfo object. All dates are ISO 8601 UTC strings.
| Field | Type | Description |
|---|---|---|
createdAt | string | When the payment was created. |
createdBy | string | Who created it. |
updatedAt | string | When the payment last changed. Use it to discard deliveries older than the state you already hold. |
updatedBy | string | Who changed it last. |
submittedAt | string or null | When the payment was submitted. null until then. |
estimateDeliveryAt | string or null | When the payee is expected to receive the money. null until known. |
Payment statuses
| Status | Meaning |
|---|---|
DRAFT | Created and not submitted. You can edit, submit or cancel it. |
SUBMITTED | Submitted and queued. It stays here while funding and checks complete. |
WAITING_PAYABILITY | Submitted with auto-submit on, waiting for the payee to finish onboarding. It continues on its own once the payee is payable. |
WAITING_PAYMENT_METHOD | Waiting for the payee to add or fix a payout method. |
WAITING_COMPLIANCE | Held for a compliance review. |
RESTRICTED | Cannot be paid to the payee's country under the batch's country restrictions. |
PROCESSING | Sent to the payout network. The money is in flight. |
COMPLETED | Paid to the payee. |
FAILED | The payout attempt failed. The payment can be submitted again. |
RETURNED | Paid, then sent back by the receiving bank or provider. refundAmount shows what came back to your ledger account. The payment can be submitted again. |
CANCELLED | Cancelled. It will not be paid. |
EXPIRED | Not paid in time and closed automatically. It will not be paid. |
New statuses may be added. Treat a value you do not recognise as "in progress" and fetch the payment if you need detail.
Example
The full request body Payment Labs sends:
{
"payorId": "C-01JBX2Q8F4H6K8M0N2P4R6T8VW",
"event": "payment-created",
"timestamp": "2026-03-14T14:02:12.871Z",
"data": {
"id": "P-01JC8Z4M6Q2W3E4R5T6Y7U8I9O",
"batchId": "B-01JC8Z1B2C3D4E5F6G7H8J9K0M",
"batchName": "March tournament prizes",
"referenceId": "prize-2026-03-0042",
"payee": {
"id": "U-01JBX6M2N8P4Q6R8S0T2V4W6Y8",
"userId": "U-01JBX6M2N8P4Q6R8S0T2V4W6Y8",
"payorId": "C-01JBX2Q8F4H6K8M0N2P4R6T8VW",
"referenceId": "player-1042",
"email": "[email protected]",
"payable": true,
"onboarded": true
},
"payablePayee": {
"id": "U-01JBX6M2N8P4Q6R8S0T2V4W6Y8",
"userId": "U-01JBX6M2N8P4Q6R8S0T2V4W6Y8",
"payorId": "C-01JBX2Q8F4H6K8M0N2P4R6T8VW",
"referenceId": "player-1042",
"email": "[email protected]",
"payable": true,
"onboarded": true
},
"payorMemo": "Second place, spring finals",
"auditInfo": {
"createdBy": "[email protected]",
"updatedBy": "[email protected]",
"createdAt": "2026-03-14T14:02:11.000Z",
"updatedAt": "2026-03-14T14:02:11.000Z",
"submittedAt": null,
"estimateDeliveryAt": null
},
"isAutoSubmitOn": false,
"submitted": false,
"completed": false,
"sourceAmount": {
"value": 1250,
"wholeValue": 125000,
"currency": "USD",
"formattedValue": "$1,250.00",
"digits": 2
},
"status": "DRAFT",
"paymentCategory": "online-esport-prize",
"payeeMemo": "Congratulations on your spring finals result",
"ledgerAccount": "01JB2Y7X6W5V4U3T2S1R0Q9P8N",
"virtualPayment": false,
"tagKeys": [
"season"
],
"tags": [
{
"key": "season",
"value": "spring-2026"
}
],
"chargedServiceFee": {
"value": 2.5,
"wholeValue": 250,
"currency": "USD",
"formattedValue": "$2.50",
"digits": 2
},
"taxJurisdiction": "us",
"lastActivity": "2026-03-14T14:02:11.000Z",
"isAutoSubmittable": true,
"isSubmittable": true,
"isEditable": true,
"isCancellable": true,
"isServiceFeeRefundable": true
}
}