Response Model and Error Handling

Last changes: 07-04-2023

With SmartPay 2.0 we unified the modification API and transaction status API responses, to always provide you with the latest transaction information and the full transaction status history in the same model. 

API Response Parameter

Level 1 response structure

Field Description Type
reconciliationReferenceId External payment provider unique transaction identifier. String
description Transaction description, as specified by you in the checkout API request. String
paymentStatus Current status of the initial payment transaction. String, see payment status model
creationDate Transaction creation date and time. String
lastStatusDate Transaction status changing date and time. String
transactionOverview Collection of initial payment transaction data. Object, see level 2 transaction overview.
modifications Array of all performed transaction modifications. Array, see level 2 modifications.

Level 2 response structure - transaction overview

Transaction overview object is returning you basic information of the transaction including the payment option type, as chosen by the consumer.

Field Description Type
transactionId The unique identifier of the transaction generated on transaction creation. String
paymentMethod Used payment option code. Payment option code, see data model
customerAccountId Unique customer identifier. String
amount Transaction modification amount. Decimal
currencyCode Transaction modification currency. The 3-letter currency ISO-4217 code. String

Level 2 response structure - modifications

To check the status of modifications initiated by you via API call, please evaluate the respective modification inside the modifications object.

Field Description Type
modificationData Additional details on the modification. ModificationData
modificationData-type Type of performed transaction modification. Possible values: "CAPTURE", "CANCELLATION", "CHARGEBACK", "SETTLEMENT", "REFUND" according to the respective API methods. String
modificationData-modificationId Your unique reference for the requested modification. String
modificationData-reconciliationReferenceId External provider unique transaction identifier. String
modificationAmount Requested transaction amount information. Amount
modificationAmount-description Description provided for the modification. String
modificationAmount-amount Transaction modification amount. Decimal
modificationAmount-currencyCode Transaction modification currency. The 3-letter currency ISO-4217 code. String
status Actualized transaction or refund status after the performed modification. String
error Error code in case of a failed modification. Please refer to the section "error field" below. String
creationDate Modification transaction creation date and time. String
statusHistory The array of status history elements. Contains information about each modification (with one modificationId) status transition. Sorted by status modification entry creation date. Array of StatusHistory
statusHistory-status Status of the transaction modification or initial payment transaction. Refer to Payment Status. String
statusHistory-statusDate Modification transaction status changing date and time. String
statusHistory-modificationAmount Requested transaction amount information. Amount
statusHistory-error Error code in case of a failed modification. Please refer to the section "error field" below. String

"error" field:

The value of the field "error" as descibed above contains a code depending on the nature of the failure reason and the the possible values are as defined on the table below:

ErrorDescriptionAction
gateway_processingRejected by the payment gatewayContact customer support
processing_errorThe payment couldn't be processedContact customer support
payment_provider_processingRejected by the payment providerContact customer support
payment_provider_card_stolenThe card has been marked as stolen
For CITs (Customer Initiated Transaction): Prompt consumer to retry with another payment instrument
For MITs (Merchant Initiated Transaction): Contact consumer to update their registered payment option
payment_provider_card_restrictedThe card usage has been restricted
payment_provider_card_not_supportedThis card type can't be authorized
payment_provider_card_invalidInvalid card details
payment_provider_card_expiredThe expiry date is passed or wrongFor CITs (Customer Initiated Transaction): Prompt consumer to retry with another payment instrument
For MITs (Merchant Initiated Transaction): Contact consumer to update their registered payment option
 
payment_provider_card_blockedThe card is blocked
payment_provider_card_declinedDeclined by the authorisation system

 

Success

The sample below shows a checkout without auto-capture. After authorization a capture API and refund API have been called and executed.

200 (OK)
Content-Type: application/json
  
{
    "reconciliationReferenceId": "pzFdwq0ImRFYGYuq41xCH",
    "description": "Purchase 1x product ABC",
    "paymentStatus": "CAPTURED",
    "creationDate": "2020-12-15T14:38:59.150Z",
    "lastStatusDate": "2020-12-15T14:40:25.008Z",
    "transactionOverview": {
        "amount": 10.99,
        "currencyCode": "EUR",
        "transactionId": "aeaabe56-3c05-44fb-9f19-9f27074ef5a4",
        "paymentMethod": "CARDS",
        "customerAccountId": "Test-account-ID"
    },
    "modifications": [
        {
            "modificationData": {
                "type": "CAPTURE",
                "modificationId": "jhgjhabkjh58gjgkjhlkjkhgkjhg6",
                "captureId": "1e953ae6-0fb1-4036-b2ba-3602059cbe9d",
                "reconciliationReferenceId": "pzFdwq0ImRFYGYuq41xCH"
            },
            "modificationAmount": {
                "amount": 10.99,
                "currencyCode": "EUR"
            },
            "status": "CAPTURED",
            "creationDate": "2020-12-15T14:38:59.150Z",
            "statusHistory": [
                {
                    "status": "CAPTURE_PENDING",
                    "statusDate": "2020-12-15T14:40:07.406Z",
                    "modificationAmount": {
                        "amount": 10.99,
                        "currencyCode": "EUR"
                    }
                },
                {
                    "status": "CAPTURED",
                    "statusDate": "2020-12-15T14:40:08.678Z",
                    "modificationAmount": {
                        "amount": 10.99,
                        "currencyCode": "EUR"
                    }
                }
            ]
        },
        {
            "modificationData": {
                "type": "REFUND",
                "modificationId": "Customer-Refund-1",
                "refundId": "e240601b-87ff-4ce1-8f60-2081b819d681"
            },
            "modificationAmount": {
                "amount": 10.99,
                "currencyCode": "EUR"
            },
            "status": "REFUNDED",
            "creationDate": "2020-12-15T14:38:59.150Z",
            "statusHistory": [
                {
                    "status": "REFUND_PENDING",
                    "statusDate": "2020-12-15T14:40:23.901Z",
                    "modificationAmount": {
                        "amount": 10.99,
                        "currencyCode": "EUR"
                    }
                },
                {
                    "status": "REFUNDED",
                    "statusDate": "2020-12-15T14:40:25.008Z",
                    "modificationAmount": {
                        "amount": 10.99,
                        "currencyCode": "EUR"
                    }
                }
            ]
        }
    ]
}

Processing Failure

Status Code:

400

Header:

Content-Type: application/json
Accept-Language: en-US

{
"reconciliationReferenceId": "FJ9wbkRjJZsRYCrjgaGGY",
"description": "Test transaction 123",
"paymentStatus": "CAPTURED",
"creationDate": "2020-12-15T14:35:44.532Z",
"lastStatusDate": "2020-12-15T14:36:45.031Z",
"transactionOverview": {
    "amount": 35.99,
    "currencyCode": "EUR",
    "transactionId": "66df9b30-c00a-45ff-afa2-c259e7c4b8f6",
    "paymentMethod": "IDEAL"
},
"modification": {
    "modificationData": {
        "type": "REFUND",
        "modificationId": "Refund-1234",
        "reconciliationReferenceId": "FJ9wbkRjJZsRYCrjgaGGY"
    },
    "modificationAmount": {
        "amount": 35.99,
        "currencyCode": "EUR"
    },
    "status": "FAILED",
    "error":"payment_provider_processing",
    "creationDate": "2020-12-15T14:35:44.532Z",
    "statusHistory": [
    {
        "status": "REFUND_PENDING",
        "statusDate": "2020-12-15T14:36:44.328Z",
        "modificationAmount": {
            "amount": 35.99,
            "currencyCode": "EUR"
        }
    },
    {
        "status": "FAILED",
        "error":"payment_provider_processing",
        "statusDate": "2020-12-15T14:36:44.852Z",
        "modificationAmount": {
            "amount": 35.99,
            "currencyCode": "EUR"
        }
    }
    ]
}
}

Validation Error

Status Code:

400

Header:

Content-Type: application/json
Accept-Language: en-US

{
    "message": [
        "modificationId must be a string",
        "modificationId must be shorter than or equal to 64 characters",
        "modificationId should not be empty"
    ]
}

Document version 1.3 - 2021-05-10 - Updated description of modification reference

2021-03-17 - Added "description" field for modifications to response.

2021-01-28 - note regarding CARDS payment option code added.