Sent when a payment reaches a status you need to act on, such as COMPLETED, FAILED or RETURNED.
payment-status-changed follows a payment through payout. Use it to learn when a payee was paid, when a payout failed or came back, and when a payment needs your attention.
When it fires
When processing moves the payment to one of these statuses:
| Status reached | Notes |
|---|---|
SUBMITTED | Can fire more than once while the payment is SUBMITTED. |
PROCESSING | |
COMPLETED | |
FAILED | |
RETURNED | |
WAITING_COMPLIANCE | Can arrive later than the status change. |
WAITING_PAYMENT_METHOD | |
RESTRICTED | When the restriction is found during processing. A payment created as RESTRICTED fires payment-created only. |
CANCELLED | When you cancel the payment with Cancel Payment, or it is cancelled for you. |
EXPIRED | When the payment is closed because it was not paid in time. |
It does not fire when a payment is created (DRAFT), when it waits for the payee to become payable (WAITING_PAYABILITY), or for edits. Use payment-changed if you need those.
For a virtual payment, it fires only when the payment reaches COMPLETED.
The payload is the payment as it is when the webhook is sent, not when the status changed. A payment that moved quickly can arrive with a later status than the one that triggered the event, and two deliveries can carry the same status. Always act on data.status.
What to do
data.status | Suggested action |
|---|---|
COMPLETED | Mark the payout as paid in your system. |
FAILED | Tell your team or the payee. Fix the cause, then submit the payment again with Submit Payment. |
RETURNED | The money is back in your ledger account (refundAmount). Ask the payee to check their payout method, then submit again. |
WAITING_PAYMENT_METHOD | Ask the payee to add or fix a payout method. |
WAITING_COMPLIANCE | No action. The payment continues or fails after review. |
RESTRICTED | The payee's country is blocked for this batch. Cancel the payment or change the batch restrictions. |
CANCELLED, EXPIRED | Close the payout in your system. cancellationReason says why. |
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-status-changed",
"timestamp": "2026-03-15T09:41:04.118Z",
"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-15T09:41:03.402Z",
"submittedAt": "2026-03-14T14:30:00.000Z",
"estimateDeliveryAt": "2026-03-16T14:30:00.000Z"
},
"isAutoSubmitOn": false,
"submitted": true,
"completed": true,
"sourceAmount": {
"value": 1250,
"wholeValue": 125000,
"currency": "USD",
"formattedValue": "$1,250.00",
"digits": 2
},
"status": "COMPLETED",
"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",
"destinationAmount": {
"value": 1250,
"wholeValue": 125000,
"currency": "USD",
"formattedValue": "$1,250.00",
"digits": 2
},
"lastActivity": "2026-03-14T14:30:00.000Z",
"isAutoSubmittable": false,
"isSubmittable": false,
"isEditable": false,
"isCancellable": false,
"isServiceFeeRefundable": false
}
}