How can I know a payment is failed/expired?

[motorina0]

This question is part of the LNbits integration with Phoenixd as a funding source.

Steps:

• I am creating an invoice using this endpoint:
  • https://phoenix.acinq.co/server/api#create-bolt11-invoice
• this invoice is never paid
• I want to know when the invoice is expired so that I can change the flag also in our DB
• this is the endpoint I'm using for checking the status:
  • https://phoenix.acinq.co/server/api#create-bolt11-invoice

Questions:

1. what is the proper way know when the invoice is expired?
2. is 404 the official failed/expired response?

The same question for outgoing payments (but more critical since it can lead to lose of funds).

[pm47]

what is the proper way know when the invoice is expired?

The invoice contains a creation timestamp and an expiry in seconds (optional, default 3600s if not specified). You can use any Lightning library (or use the decodeinvoice endpoint) to parse the invoice and compute: expiryTimestamp = creationTimestamp + expirySeconds.

this is the endpoint I'm using for checking the status:
https://phoenix.acinq.co/server/api#create-bolt11-invoice

This creates a new invoice, it doesn't return the status of an existing invoice

The same question for outgoing payments

I'm assuming you want to check if an outgoing payment is pending or completed (as a side note, this is technically not symmetrical at all to an unpaid invoice).

Use GET /payments/outgoing/{paymentId} or GET /payments/outgoingbyhash/{paymentHash}:

• if completedAt=null and isPaid=false: pending
• if completedAt!=null and isPaid=false: failed
• if completedAt!=null and isPaid=true: succeeded

[motorina0]

Thank you!

This creates a new invoice, it doesn't return the status of an existing invoice

• my bad

---

Use GET /payments/outgoing/{paymentId} or GET /payments/outgoingbyhash/{paymentHash}:
if completedAt=null and isPaid=false: pending
if completedAt!=null and isPaid=false: failed
if completedAt!=null and isPaid=true: suceeded

• is this documented in the API documentation?
• if this logic changes then the side effects can be dangerous

---

Can you please also clarify question 2 of the original post?

• what is the meaning of 404 when one calls GET /payments/outgoingbyhash/{paymentHash} or GET /payments/incoming/{paymentHash} with a valid hash (previously returned by phoenixd)

[pm47]

Use GET /payments/outgoing/{paymentId} or GET /payments/outgoingbyhash/{paymentHash}:
if completedAt=null and isPaid=false: pending
if completedAt!=null and isPaid=false: failed
if completedAt!=null and isPaid=true: succeeded

is this documented in the API documentation?
if this logic changes then the side effects can be dangerous

Actually, no. Will do in https://phoenix.acinq.co/server/api#get-outgoing-payment (cc @dpad85).
The logic will not change, but while we are at it, we could add a simple status field with values PENDING/FAILED/SUCCEEDED.

what is the meaning of 404 when one calls GET /payments/outgoingbyhash/{paymentHash} or GET /payments/incoming/{paymentHash} with a valid hash (previously returned by phoenixd)

It means that there are no payments with this paymentHash.

Note that the initial API is pretty raw and inconsistent and will be revamped at some point. But we are very careful with backward compat and when that happens we will keep the old and new APIs for an extended period of time.