Get transaction results from a webhook

The Get transactions result through an API section describes a way to retrieve the status of a transaction by making a call to an endpoint. It involves the client performing polling to receive information about the created transactions, where the endpoint can be called multiple times for the same transaction to obtain its most recent status. However, using webhooks, IDPay can notify a specific client endpoint every time the status of a transaction changes.

What is a webhook?

A webhook is a systemic notification service that allows asynchronous integration between systems by triggering notifications to the other system. Webhooks enable systems to stay updated with the latest information without the need for constant polling for updates.

Information required for webhook configuration

The following information is required to configure the webhook:

• Notification URL: The endpoint where IDPay will notify about status updates.
• Authentication Type: The authentication method used to invoke the endpoint, which should be one of the following options:
  • Basic Authorization
  • API Key
  • No authentication
• Secret: The secret used for authentication. It is only required for Basic Authorization and API Key.
  • For Basic Authentication, it needs to be in the following format: user:pass
  • For API Key, may have two formats:
    • header:value, when you want to specify a header name
    • value, when the desired header is Authorization
• Retry Settings: Retry settings for failed endpoint calls:
  • Maximum number of retries
  • Retry interval (in seconds)
  • Rate limit: Maximum limit of simultaneous sends (maximum: 500)
  • Timeout: Maximum waiting time for the endpoint response (in seconds)

Integration with IDPay

By setting up a webhook in IDPay, the client can receive information about transactions through notifications sent to an endpoint of their API to receive these updates.

The information sent by IDPay to the client's API will include:

• ID: Transaction ID
• status: Transaction status, which can be one of the following:
  • approved: Approved transaction
  • processing: Transaction in processing
  • inconclusive: Unable to perform a conclusive validation
  • shared: Shared transaction, awaiting submission
  • skipped: The person skipped the biometric capture in the flow
  • unknown-share: The person marked that they do not recognize the purchase
  • absent-holder: The cardholder is not present to perform the capture
  • expired: The cardholder did not perform the capture within the established time and the transaction has expired

Note that it is possible to choose which status notifications the client wants to subscribe to through webhook configuration. After sending this information, the expected response should be synchronous.

Authentication

The API can be protected by an authentication method, either Basic Authentication or an API Key. A list of valid IPs for access can also be defined for additional protection.

Request

The request should be a POST method in a REST API, making it easier and more secure to send the information. All fields should be mandatory. The request body should accept the transaction ID and status, as shown in the example below:

{
  "id": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "status": "approved"
}

Response

The response should be synchronous. The status for successful requests should be in the range of 200 to 299. Any other statuses will be considered a failure and IDPay will make new notification attempts (with exponential backoff between them) until receiving a 2xx response or reaching the maximum number of attempts.

Response Status

Currently, we have a set of statuses, but it may vary in the future. Therefore, we recommend making the statuses that the client is interested in configurable to take appropriate actions. For example, if it is prefferable to take action every time a successful capture is made, this occurs with the processing status. However, since this may change in the future, it is recommended to make the status indicating a successful capture configurable in the system so that a future change to the captured status can be easily made.

Additionally, we recommended having specific actions for specific statuses and a general action if the status is not recognized (e.g., assuming that anything other than processing and approved is inconclusive). This is important because new statuses may arise in the future, and the webhook is not expected to break as a result.

Important Considerations

Pay attention to the following aspects when developing the API that IDPay will use to notify status changes:

Rate Limit

To avoid overloading client resources when there are many concurrent transactions, it is possible to specify an upper limit on the number of times the endpoint can be called.

Idempotence

The current webhook implementation guarantees at-least once delivery so we may notify the same status more than once. The endpoint implementation should be aware of this and be implemented in an idempotent manner.

Fallback

In case of any unavailability in the webhook service, it is recommended to have a fallback method so that the client can continue to obtain transaction statuses within the established response time. The endpoint query described in the Get Transaction Result section can be used for this purpose.

Questions?

If you have any questions or need further assistance, if you are already a client or partner, you can contact us through the Help Center.