Skip to main content

Transaction Response

We are improving our documentation

We're currently working on improving this page to provide you with the best possible experience. Please bear with us while we make some changes.

Thank you for your patience!

As response to the API call the IXOPAY platform answers with a Result JSON with the status and further instructions.

Generally there are 4 possible results:

FINISHED​

The transaction completed and was processed successfully. You can deliver the ordered goods.

note

Recurring Transaction

If you flagged the transaction as withRegister or if the transaction was a Register, you will use the uuid for recurring charges in the field referenceUuid.

{
  "success": true,
  "uuid": "d94c0d72f3a36e21f16e",
  "purchaseId": "20241126-d94c0d72f3a36e21f16e",
  "returnType": "FINISHED",
  "paymentMethod": "Creditcard",
  "returnData": {
    "type": "visa",
    "cardHolder": "Alex Smith",
    "expiryMonth": "11",
    "expiryYear": "2029",
    "binDigits": "41111111",
    "firstSixDigits": "411111",
    "lastFourDigits": "1111",
    "merchantFingerprint": "9s92FBBvMuw7nn8t7ChHDRuFXS6gZOnHymbGnO/BZBUw3j25LW6dcl50aHWTcdJtSFDvTqLPM4stZLbGb6EVpQ",
    "globalFingerprint": "bSDn7SmA3Wr/o7Pzh4TaEw6RHc6rwqKxNFW8opklNbP7irUxv57avJPKveRO48fGhKY0oJYWUAfMcJq9+iSUmw",
    "_TYPE": "creditcardData"
  }
}

ERROR​

The transaction failed or was declined. See the error code and message for further details.

You will find the native error message and code from the payment provider/acquiring bank in the fields adapterMessage and adapterCode.

Merchant Advice Code

When supported by an adapter implementation, a merchant advice code can be returned with the ReturnData.

This code is piped through as received by the IXOPAY platform.

If a merchant advice code indicating a hard "do not retry" is returned, the value "doNotResubmit": true will additionally be returned with the error response extra data.

{
  "success": false,
  "uuid": "d94c0d72f3a36e21f16e",
  "purchaseId": "20241126-d94c0d72f3a36e21f16e",
  "returnType": "ERROR",
  "paymentMethod": "Creditcard",
  "returnData": {
    "type": "visa",
    "cardHolder": "Alex Smith",
    "expiryMonth": "11",
    "expiryYear": "2029",
    "binDigits": "41111111",
    "firstSixDigits": "411111",
    "lastFourDigits": "1111",
    "merchantFingerprint": "9s92FBBvMuw7nn8t7ChHDRuFXS6gZOnHymbGnO/BZBUw3j25LW6dcl50aHWTcdJtSFDvTqLPM4stZLbGb6EVpQ",
    "globalFingerprint": "bSDn7SmA3Wr/o7Pzh4TaEw6RHc6rwqKxNFW8opklNbP7irUxv57avJPKveRO48fGhKY0oJYWUAfMcJq9+iSUmw",
    "_TYPE": "creditcardData"
  },
  "errors": [
    {
      "errorMessage": "The transaction was declined",
      "errorCode": 2003,
      "adapterMessage": "Transaction declined",
      "adapterCode": "transaction_declined"
    }
  ]
}

REDIRECT​

You must redirect the user to the URL defined in redirectUrl to proceed with the transaction. Afterwards the user will be back redirected to your website (one of the URLs you defined in the API call in successUrl, cancelUrl or errorUrl). In parallel the IXOPAY platform sends a status notification to you callbackUrl with the final result.

note

For the final result you should only trust the notification, NOT the back redirection!

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

PENDING​

The transaction was accepted for processing, but is not yet completed. You will receive a status notification to the URL you defined in callbackUrl once it reaches a final state.

Depending on the payment method, this can take from seconds up to several days.

{
  "success": true,
  "uuid": "d94c0d72f3a36e21f16e",
  "purchaseId": "20241126-d94c0d72f3a36e21f16e",
  "returnType": "PENDING",
  "paymentMethod": "Creditcard",
  "returnData": {
    "type": "visa",
    "cardHolder": "Alex Smith",
    "expiryMonth": "11",
    "expiryYear": "2029",
    "binDigits": "41111111",
    "firstSixDigits": "411111",
    "lastFourDigits": "1111",
    "merchantFingerprint": "9s92FBBvMuw7nn8t7ChHDRuFXS6gZOnHymbGnO/BZBUw3j25LW6dcl50aHWTcdJtSFDvTqLPM4stZLbGb6EVpQ",
    "globalFingerprint": "bSDn7SmA3Wr/o7Pzh4TaEw6RHc6rwqKxNFW8opklNbP7irUxv57avJPKveRO48fGhKY0oJYWUAfMcJq9+iSUmw",
    "_TYPE": "creditcardData"
  }
}
Last updated on