Skip to main content

Transaction Status

The status and the final details of a transaction can be requested from the Payen Platform.

To obtain the transaction status, the merchant sends a server-to-server Status Request to the Payen Platform using the responseKey.

The responseKey uniquely identifies the transaction and allows the merchant to retrieve the current or final status of the payment.

Status Request Message​

Details of the status request can be found in the Status Request

An example of such a message is shown below:

Status Request example
 {
     "version": 2,
     "merchantId": 10000001,
     "responseKey": "e174dfd944bb481d8be242e79c941264"
 }

Status Response Message​

The status response message describes the final details of a transaction from the Payen Platform. The same format is also used for the Asynchronous Notification Message which is sent "server to server" to the notification URL (if provided) in the original initialisation request.

An example of such a message is shown below:

Status Response example
{
  "version": 2,
  "type": "PAYMENT",
  "customerId": "12345",
  "merchant": {
      "merchantId": "10000001",
      "accountId": "20000001"
  },
  "transaction": {
      "amount": 1000,
      "currency": "GBP",
      "merchantRef": "Fh8F9fEpeK8qUFMHt0Vl",
      "gatewayRef": "56dsfds873wHJK32yuiv",
      "transactionType": "ECOMMERCE"
  },
  "status": {
      "code": "SUCCESS",
      "message": "Request Successful",
      "timestamp": "2012-06-21T16:56:39.154+01:00",
      "operationRef": "01K59QF7Z74G51STE8H8A84C2J"
  },
  "paymentHistory": {
      "paymentAttempt": {
          "order": 1,
          "timestamp": "2012-06-21T16:56:39.154+01:00",
          "code": "SUCCESS",
          "operationRef": "01K59QF7Z74G51STE8H8A84C2J",
          "thirdPartyRef": "123",
          "amount": 136400,
          "currency": "USD",
          "paymentMethodType": "SID_EFT",
          "token": "21fds873wHJK32ewr43"
      }
  }
}

Platform Asynchronous Notification Message​

If a notification URL was provided in the Payen Platform request message, then an asynchronous notification will be sent to the notification URL. This is a message containing all the details of the transaction. This method of notification is designed to make sure that the response is always received by the merchant, even if there are browser/connection problems during the previous step.

Notification Status Response Message​

The status response message describes the final details of a transaction from the Payen Platform, and is sent to the notification URL (if provided) in the original Payen Platform Request Message, after the response has been received from the processing. The same format is also used in response to an Payen Platform Status Request Message. See above.

Field Specific Details​

The following provide more details to some of the fields described in the previous section.

code​

The code element in the response contains a distinct set of values and can be located within the status element. The possible values are described below:

ValueDescription
SUCCESSThe request was processed successfully. In the case of a status request or notification response, this response code indicates that the transaction was successful. If the code is anything other than SUCCESS then the request was not successful.
REJECTEDThe request was rejected. If this code is received then there will be a reasons element with one or more reason child elements. These child elements will contain individual reasons as to why the request was rejected. The individual reasons come in the form of codes that represent rejection reasons that can be found in the response codes manual.
ERRORAn error has occurred during the processing of the transaction and should be treated as a priority as this response will be rare. If this does occur please contact support.
DECLINEDThis response code indicates that the transaction was declined. An example of a decline might be if there are limits set around the number of retries a customer has to add a card successfully.
CANCELLEDThis response code indicates that the customer has chosen to cancel the transaction.
PENDINGThe transaction is still in progress and a final outcome is not yet available. This may occur while the customer is completing the payment with the APM provider, while waiting for a provider response, during asynchronous processing, or when additional steps (e.g. authentication or provider confirmation) are required. The final status should be obtained via a subsequent status request or notification.
RESUBMISSIONThe request was not processed because a similar transaction has already been initiated. This typically occurs when a duplicate initialisation request is submitted for the same transaction. The merchant should avoid retrying the initialisation and instead use the existing transaction reference to continue or query the status.

locale​

The locale field is used to display the correct language to the user in the Payen Platform. The locale field format is as follows:

<language>_<country>

e.g. en_US gives us a language of English and a country of United States.

The language argument is a valid ISO Language Code. These codes are the lower-case, two-letter codes as defined by ISO-639. You can find a full list of these codes at a number of sites, such as: ISO 639

The country argument is a valid ISO Country Code. These codes are the upper-case, two-letter codes as defined by ISO-3166. You can find a full list of these codes at a number of sites, such as: ISO-3166

For more information please the following reference: locales