status to understand the Lead-side lifecycle of an instant payment, counterparty_status to understand the counterparty-side lifecycle for outgoing payments after the payment reaches posted, rejection hash to determine who rejected a payment and why, and related_objects to reconcile returns. The status field of the instant_payment object governs funds flow with respect to your account. Funds have moved only if it is posted. The counterparty_status field, on the other hand, tells you where funds are after they have left your account.
Outgoing payment rejected by Lead or the network
This is an outgoing instant payment that did not make it to the counterparty. In this case, the payment is rejected on theinstant_payment object, and the rejection hash identifies lead or network as the rejecting party and provides the rejection reason and details.
You should handle the .rejected webhook and inspect the rejection hash for reason and details. Follow up with Lead if necessary.
Outgoing payment rejected by the counterparty
This is an outgoing instant payment that Lead submitted to the network which the counterparty rejected. Lead exposes this on the rejection hash and identifiescounterparty as the rejecting party and provides the rejection reason and details.
You should handle the .rejected webhook and inspect the rejection hash for reason and details. Retry the payment if appropriate.
Outgoing payment posted but subsequently rejected by counterparty
This is not a send-time rejection. Theinstant_payment status was posted to the Lead account, but the counterparty_status was subsequently updated to rejected. The original payment reached the end of its lifecycle. Separately, a return is expected from the counterparty and modeled via a separate instant_payment object linked to the original payment through related_objects.
You should handle the .counterparty_status_updated webhook and inspect the rejection hash for reason and details. You should also reconcile the original rejected payment against the subsequent return which is handled like any ordinary payment: listen to the .posted webhook and inspect related_objects.original_payment_id.
Incoming payment rejected by account number controls
This is an incoming instant payment that Lead rejects. The most common rejection occurs on the basis of partner-configured account number controls which allow you to control what counterparties are allowed to initiate incoming payments. You should handle the.rejected webhook and inspect the rejection hash for reason and details. If you see unexpected rejections on the basis of account number controls, you should update your account number controls accordingly.
Incoming payment accepted but subsequently returned
This is an incoming payment that you don’t want to accept. Lead does not offer a mechanism for you to reject the payment outside of account number controls. Instead, you need to return the payment. You should return the payment viaPOST /instant_payments/{id}/return, which creates a new outgoing return.