Skip to main content

Transaction return types

Within the IXOPAY platform, transactions can result in one of five return states. Each state is returned in the returnType field of the transaction response and provides information about the transaction status and the outcome. Below is a detailed explanation of each state.

Finished​

A FINISHED state indicates that the transaction was successfully processed and completed. This signifies that you are now clear to deliver the ordered goods or services.

Recurring Transactions

For transactions flagged with withRegister or Register transactions, use the uuid of the finished transaction for subsequent recurring charges, placing it in the referenceUuid field.

Response example
{
  "success": true,
  "uuid": "d94c0d72f3a36e21f16e",
  "purchaseId": "20240904-d94c0d72f3a36e21f16e",
  "returnType": "FINISHED",
  "paymentMethod": "Creditcard",
  "returnData": {
    "type": "visa",
    "cardHolder": "Alex Smith",
    "expiryMonth": "9",
    "expiryYear": "2029",
    "binDigits": "41111111",
    "firstSixDigits": "411111",
    "lastFourDigits": "1111",
    "_TYPE": "creditcardData"
  }
}

Redirect​

A REDIRECT state is returned for scenarios like Hosted Payment Pages or 3-D Secure authentication where the user needs to be redirected to the redirectUrl to proceed with the transaction. After completion, the user will be redirected back to your site using one of the URLs specified (successUrl, cancelUrl, or errorUrl). Simultaneously, IXOPAY will send a status notification with the transaction result to your callbackUrl.

note

Rely on the status notification to ascertain the final transaction outcome, not the user's redirection back to your provided URLs (successUrl, cancelUrl, or errorUrl).

Response example
{
  "success": true,
  "uuid": "d94c0d72f3a36e21f16e",
  "purchaseId": "20240904-d94c0d72f3a36e21f16e",
  "returnType": "REDIRECT",
  "redirectUrl": "https://gateway.ixopay.com/redirect/d94c0d72f3a36e21f16e/ABCDEF01234567890ABCDEF01234567890",
  "paymentMethod": "Creditcard"
}

Pending​

A PENDING state means the transaction has been accepted for processing but hasn't yet completed. You will receive a status notification at your callbackUrl when the transaction reaches its final state. Completion times can vary, ranging from seconds to several days, depending on the payment method.

Response example
{
  "success": true,
  "uuid": "d94c0d72f3a36e21f16e",
  "purchaseId": "20240904-d94c0d72f3a36e21f16e",
  "returnType": "PENDING",
  "paymentMethod": "Creditcard",
  "returnData": {
    "type": "visa",
    "cardHolder": "Alex Smith",
    "expiryMonth": "9",
    "expiryYear": "2029",
    "binDigits": "41111111",
    "firstSixDigits": "411111",
    "lastFourDigits": "1111",
    "_TYPE": "creditcardData"
  }
}

Pending DCC​

A PENDING_DCC state means that the Dynamic Currency Conversion (DCC) is being processed. During this state, the transaction is paused until the continue-dcc endpoint is called, after which the transaction proceeds. More details on the process can be found in the Dynamic currency conversion (DCC) reference article.

Response example
{
  "success": true,
  "uuid": "d94c0d72f3a36e21f16e",
  "purchaseId": "20240904-d94c0d72f3a36e21f16e",
  "returnType": "PENDING_DCC",
  "dccData": {
    "uuid": "10987654321",
    "originalAmount": "155.00",
    "originalCurrency": "EUR",
    "convertedAmount": "200",
    "convertedCurrency": "USD",
    "conversionRate": "1.28",
    "disclaimer": "string",
    "markUp": "1.6"
  }
}

Error​

An ERROR state signifies a failed or declined transaction. The errors field in the response, an array of error objects, provides insights into the issue. These objects contain fields like errorMessage, errorCode, adapterMessage, and adapterCode that further elaborate on the failure. For more information, refer to the Handling Errors section.

Merchant Advice Codes

Some adapters may support Merchant Advice Codes, a set of codes introduced by credit card schemes to provide feedback on handling failed transactions. If a Merchant Advice Code is returned with the response, you will find it in the returnData.merchantAdviceCode field. For more detailed information on Merchant Advice Codes, visit the Merchant advice codes section.

Response example
{
  "success": false,
  "uuid": "d94c0d72f3a36e21f16e",
  "purchaseId": "20240904-d94c0d72f3a36e21f16e",
  "returnType": "ERROR",
  "paymentMethod": "Creditcard",
  "returnData": {
    "type": "visa",
    "cardHolder": "Alex Smith",
    "expiryMonth": "9",
    "expiryYear": "2029",
    "binDigits": "41111111",
    "firstSixDigits": "411111",
    "lastFourDigits": "1111",
    "_TYPE": "creditcardData"
  },
  "errors": [
    {
      "errorMessage": "The transaction was declined",
      "errorCode": 2003,
      "adapterMessage": "Transaction declined",
      "adapterCode": "transaction_declined"
    }
  ]
}
Last updated on