instant_payment object has an id of the form instant_payment_xyz123that references it internally within the Lead network. Additionally, Lead exposes three identifiers that identify the payment message within the payment network. None of these identifiers are configurable through the instant_payments API. Instead, Lead sets them automatically for outgoing payments and the counterparty sets them for incoming payments.
end_to_end_idis the mandatory “trace id” for instant payments that must pass through from debtor to creditor unchanged. Use it to reference a payment with the end customer or a counterparty.end_to_end_idis a max of 35 characters and is expected to be unique.transaction_idis an optional identifier assigned by the debtor or initiating party that may also be used to reference a specific payment on the network.transaction_idis a max of 35 characters and is expected to be unique.uetris an optional identifier assigned by the debtor or initiating party that may also be used to reference a specific payment on the network.uetris a UUIDv4 that is expected to be globally unique.
Payments
Payments will include two or three payment identifiers which depend on the underlying rail and the party initiating the payment. Outgoing payments from Lead will always haveend_to_end_id and transaction_id populated. FedNow and RTP require usage of end_to_end_id because it is the primary identifier to track a payment with a counterparty or an end customer. FedNow also mandates use of either transaction_id or uetr, but RTP mandates transaction_id and leaves uetr as optional.
| Instant Payment ID | Required by FedNow? | Required by RTP? | Network Message ID | Validation |
|---|---|---|---|---|
end_to_end_id | Yes | Yes | EndToEndId | Max 35 characters |
transaction_id | Yes if uetr is null | Yes | TxId | Max 35 characters |
uetr | Yes if transaction_id is null | No | UETR | UUID V4 |
Returns
Payments and returns both utilize their owninstant_payment object. Returns are identified with a non-null instant_payment.related_objects.original_payment_id . FedNow returns do not have any of their own instant_payment.payment_identifiers. To reference a FedNow return, use the end_to_end_id of the original payment. RTP returns, however, support the same set of identifiers that the original payment supports. To reference an RTP return, simply look at the end_to_end_id of the return itself.
| Instant Payment ID | Required by FedNow? | Required by RTP? |
|---|---|---|
end_to_end_id | Unsupported | Yes |
transaction_id | Unsupported | Yes |
uetr | Unsupported | No |