Payment and Transaction Statuses

When initiating a payment flow, you may have noticed that your first step is always to Create a Payment— regardless of the request you choose to invoke next.
The payment object you create will continue to represent the composite status of your payment throughout the flow. Understanding the Payment Object topic is a good place to learn more.

While your Payment Status will always refer to your payment object - and to your Payment status as a whole - your Transaction Status will represent the result of the API call you perform — Succeed, Pending, or Failed. The result will show in the response of the API request. Note that your Transaction Status will impact your Payment Status and not vice versa. Payment and Transaction Statuses give you insights into your payment’s lifecycle and may represent a finite result or indicate that you need to perform further actions in the flow:

  • A Payment status represents the status of your Payment as a whole and will get an Initialized status upon creation. You will see its status in the response of the Create a Payment request. Should you wish to check your Payment’s status afterward, you can do so anytime with the Retrieve Payment API.
  • A Transaction Status represents the result of the API call you performed and will appear in the response of the API request you invoked. The new Transaction Status will affect your Payment Status.

Payment Statuses

When you Create a Payment, it’s initial status will always be Initialized, like so:

{
    "id": "5ab9149e-b7ea-4d22-afba-bc2ea6a3b717",
    "currency": "EUR",
    "created": "1673891658236",
    "modified": "1673891658236",
    "is_disputed": false,
    "status": "Initialized",
    "billing_address": {}
}

Your payment status will subsequently change when you invoke your requests (e.g., Create an Authorization, Create a Charge), and -if the request is successful or pending - will change the payment status accordingly. Your transaction status, therefore, affects your payment status, not vice versa. A payment can receive one of the following statuses:

  • Initialized: When you first Create a Payment, this would be your Payment’s initial status. You can see it in your request’s response after invoking the Create Payment request under the status field.
  • Authorized: After invoking the Create an Authorization request, if your Payment’s authorization is successful, the new status of your Payment will be Authorized.
  • Voided: When you choose to cancel Payment and not proceed to Create a Capture after you Create an Authorization - i.e., before the money leaves the customer’s bank account - the payment status becomes Voided.
  • Captured: Indicating that your Create a Capture/Create a Charge call was successful and that your provider obtained the payment funds from your shopper.
  • Refunded: Indicating your Create a Refund request is successful.
  • Pending: Indicating that your request is pending a response from the provider, most commonly during an asynchronous flow.

Transaction Statuses

Your transaction’s status reflects the result of your latest action (usually an API call). Transaction status can indicate a finite result or imply that you must track or perform further action(s) in the flow. The status is returned in the result object, like so:

{
  "id": "21fc2c59-3e7b-4ec4-bb04-7134fb006183",
  "amount": 31602077,
  "created": "1520777438696",
  "provider_specific_data": {},
  "payment_method": {
    "token_type": "credit_card",
    "type": "tokenized",
    ...
  },
  "result": {
    "status": "Succeed"
  },
  ...
}

There are three possible transaction statuses you can see in your request’s response:

  • Succeed: Indicating that your Authorization/Capture/Charge/Refund/Void request is successful.
  • Failed: Indicating that your Authorization/Capture/Charge/Refund/Void request failed, most commonly due to an error, whether on your side or your provider’s.
  • Pending: Indicating that your request is pending response from the provider, most commonly during an asynchronous flow.

Payment Status vs. Transaction Status

To understand the interplay between Payment and Transaction statuses, it is important to note that the status of your payment will change or retain its status only according to the result of your transaction (i.e., the result of the API request you perform).

API Call Initial Payment Status Transaction Status Subsequent Payment Status Change
Capture/Charge/Authorize Initialized Succeed Captured/Authorized
Capture/Charge/Authorize Initialized Failed Initialized
Capture/Charge/Authorize Initialized Pending Pending
Void Authorized Succeed Voided
Void Authorized Failed Authorized
Void Authorized Pending Pending
Refund Captured Succeed Refunded
Refund Captured Failed Captured
Refund Captured Pending Pending
Last modified January 26, 2023