Monitoring One-Off Payment Progress

One-off payments follow a defined lifecycle, and depending on your app it can be useful to know in what state a given payment is.
Akahu provides two ways to monitor one-off payments:

Polling

API Reference

The simplest way to keep an up-to-date view of the payment is to make periodic GET requests to the /v1/one-off-payments/{paymentId} endpoint, using the payment _id returned when you created the payment. Polling will work fine for simple use-cases, however this approach is generally more brittle and less efficient.

Webhooks

Akahu supports webhooks on one-off payments by specifying the webhook_uri when creating the payment.
If this field is set, webhooks will be sent as JSON objects via an HTTP POST request whenever the payment status changes.
A webhook payload has the following fields:

Path	Example	Description
`type`	`"ONE_OFF_PAYMENT_STATUS_UPDATE"`	This will always be set to `"ONE_OFF_PAYMENT_STATUS_UPDATE"`.
`_payment`	`"one_off_payment_c012345..."`	The ID of the payment that triggered this webhook.
`status`	`"CANCELLED"`	The payment status at the time of this webhook.
`status_reason`	-	If applicable, more information about the payment status.
`status_reason.code`	`"USER_CANCELLED"`	An enum describing the reason for the payment status. Possible values can be found in the Payment Lifecycle documentation
`status_reason.message`	-	A human-readable message describing the status. Intended for developer consumption, should not be passed through to the end-user.
`emitted_at`	`"2020-01-01T00:00:00.000Z"`	The date and time that this webhook was triggered. This may be used to detect/handle out-of-order delivery.

ℹ️
Unlike webhooks sent as part of our enduring-access, one-off payment webhooks don't have a state field. Instead you can encode state as parameters in the webhook_uri when you create the payment.

Receiving webhooks

When your system receives a webhook it must return a 200-level HTTP response code within 10 seconds. In the event of a delivery failure Akahu will retry delivery up to 20 times with an exponential backoff.

While retries may resolve transient delivery failures, it is still important to consider the possibility of webhook delivery failure. For critical functionality like payments we recommend also implementing a fallback (for example a scheduled task) to check up on payment status after some time. This will ensure that your payment tracking is robust in case of webhook failures.

Webhook signatures

Akahu signs each webhook that it sends with a private RSA key. This signature allows your app to verify that it was Akahu who sent the webhook, and not another third party.

The base 64 encoded signature and the key ID are supplied in the X-Akahu-Payments-Signature and X-Akahu-Payments-Signing-Key HTTP headers.
When your system receives a webhook it should validate the webhook by:

Retrieve the signing key: Make a request to the GET /v1/webhooks/keys/{keyId} API endpoint to retrieve the corresponding public RSA key. This key should be cached.
Use the public key to verify the payload: Making sure that you're using the raw webhook payload (before any parsing takes place), verify that the body was correctly signed using RSA-SHA256. This varies by language, see our article on enduring webhooks for some examples.

Webhooks that fail signature validation should be discarded.