Skip to main content

Getting task status

Overview​

The transaction status can be checked using three methods:

  1. Webhook Notification Service
  2. Direct Status Checking
  3. task.statusGet
info

The recommended approach is to use the Webhook Notification Service

For optimal security and architectural design, it's recommended to implement a two-step verification process when handling notifications:

  • First, subscribe to webhook notifications from the API.
  • Upon receiving a notification, instead of immediately acting on its contents, perform a direct status check with the Enterprise API using the provided globalId. For transactions requiring a manual action (RFI cases), use of webhooks and task.statusGet is recommended.
warning

System operates asynchronously. When a pay.toCard request is made, it is processed by one service, status or result of this transaction needs to be propagated to other services or databases. There's a brief period where the service that processed the payment has the information, but other services (like the one responding to status requests) might not have received or processed this information yet. During this brief window, if a status check is made, the response might come back with no payment information, even though the payment has been processed.

This delay may result in the "code":3006,"comment":"Unable to find requested data. Please check the request parameters and try again." message, as the requested data is not yet available. Eventually, all parts of the system will be updated and consistent.

Webhook Notification Service​

Basic​

To use the Webhook Notification Service, Specify the endpoint URL where the notifications should be sent:

"result": [
  {
    "uri": "https://example.com",
    "method": "get"
  }
]

Basic Notification Format​

When the transaction status is updated, the system will send a notification to the configured endpoint with the following format:

"B8719542-fav4-4902-ab2c-11de595ace30"

Expanded​

This service provides a webhook with expanded structure. To configure this service, please provide the end-point planned for notification to your Paysend Implementation team.

Expanded Notification Format​

When the transaction status is updated, the system will send a notification to the configured endpoint with the following format:

{
  "webhookType": "TransactionStatusUpdate",
  "invoiceId": "ABC_TXN_123456",
  "transactionId": "d78adfce-631d-485f-af32-29cagbf95b70",
  "status": "Completed",
  "statusDateTime": "2024-08-07T20:14:01.85131+03:00",
  "errorCode": "0",
  "errorDescription": null
}

Direct Status Checking​

Steps to Check Status​

  1. Obtain the globalId from the initial transaction response.
  2. Construct the status check URL using the globalID.
  3. Send a GET request to the constructed URL.
    • Option A: Use function block URL from response.StatusURI
    • Option B: Use https://enterprise-api.paysend.com/processing/status/{GlobalId}
  4. Process the response to determine the current status of the transaction.

Use the globalID as the primary element for status checking.

  • Perform status checks at intervals of 3-5 seconds.
  • Continue the status checks until the final transaction status (successful or declined) is obtained.
  • The total duration for performing the status checks is approximately 5 to 10 minutes.
  • The only time when processing takes longer is if a transaction is placed on Compliance hold, Request For Information (RFI) was sent, and response is required before transaction is released. In this case, record the paymentID and switch to task.statusGet method.

Method Details​

Detailed endpoint description can be found on GET /processing/status page.

task.statusGet​

warning

This is a reserve way of getting task status, only for cases when due to error of some sort both globalID and paymentID have not been returned in response.

If the globalID is not available (expired after 2hrs or for RFI case management), you can use the paymentID (or invoiceId*) to retrieve the latest status of the transaction.

  • Use the paymentID for status checking.
  • Perform status checks at intervals of 1 minute, gradually increasing the interval. If both the paymentID and globalID are not available:
  • Use the invoiceID for status checking.
  • Perform status checks at intervals of 1 minute, gradually increasing the interval.
note

Most recent payment’s status with matching invoiceID will be provided in response. This method is designed to be used as a failover method in case no other method is available, but it is risky to rely on this method since invoiceID is not an idempotency key in Paysend system.

Authentication and Idempotency in API Requests​

Please check Authentication page for detailed description of Authentication and Idempotency.