Pollable Transactions

API transactions are set to a temporary status upon creation. This state does not reflect whether the transaction could actually be processed successfully by the corresponding payment gateway, and therefore is not very informative. However, most of the time merchants will want to provide immediate feedback about the true status of the payment to their customers.

One way of being notified when the status of a transaction has changed without using webhooks is to perform GET requests on the resource, until a different status is observed. However, this is a wasteful way of doing it, since it requires the merchant to implement a polling mechanism that properly handles all sorts of errors while taking into account the API’s request limits.

The API offers merchants an efficient way of polling for the status of a transaction by sending just one request to the following resources:

• Charges
• Refunds
• Cancels
• Subscriptions

When sending a GET request to one of these resources, the merchant can set the polling query parameter to true to tell the API to internally poll for the status of the transaction until it reaches a terminal state (e.g. Successful, Failed, Current, etc.). If such a status is reached within three seconds, the API returns the updated response. Otherwise, it returns the response in whatever its status is at the moment of the timeout.