Response Model and Error Handling

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

important

Technical error codes or other details of why a request could not be completed must not be disclosed to an end user directly, as this might increase the risk of fraudulent activity.

Especially when it comes to credit card fraud, fraudsters often target websites that give a different response to different types of declination (e.g., where one response is returned for the amount exceeding the available credit and another where a card is flagged as stolen).

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.

info

Within SmartPay, each order on your side is represented by one checkout transactionID. You may use this transactionID to perform the initial checkout, retrieve an overall status or for later modifications, like manual capture or refunds.

On the payment side, this may lead to multiple financial transactions, e.g., one payment transaction about the captured amount (which will be settled to your account), and later a refund transaction (which will be debited from your account / deducted from your payout).

The reconciliationReferenceId has been introduced to allow you to keep track of those financial transactions, as it represents the financial transactionID, as you would see it in the payment provider's merchant portal (e.g., our merchant panel) or settlement files.

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
mit	Flag to show if created transaction relates to merchant-initiated transactions.	Boolean
paymentOrigin	Displays the origin flag marked upon creation of the transaction.	Enumeration

info

Payment option CARDS is returned by SmartPay in case the actual card brand has not been selected by the consumer yet or if it could not be determined.

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 according to the respective API methods: CAPTURE, CANCELLATION, CHARGEBACK, SETTLEMENT, REFUND.	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

Whenever a transaction or modification fails, the response will contain an error field. This field is only present when the transaction status or a modification status is FAILED. The error field is designed for merchants to understand what went wrong during processing and to support troubleshooting with SmartPay. While these codes are essential for you, they are not intended to be shown directly to your customers. Instead, always present a generic customer-facing message (e.g., We could not process your payment. Please try again or use another payment method.) and use the error codes internally for logs, support requests, or integration analysis.

SmartPay provides detailed responses to help you understand whether a request was processed successfully or if an error occurred. Errors can appear at two different stages of processing:

• Validation errors: Detected by SmartPay before the request is forwarded to any payment provider.
• Processing errors: Returned by the payment provider or during downstream processing after the request has passed validation.

Validation Errors

Validation errors occur when the request sent to SmartPay cannot be processed because it does not comply with our data model or business rules. In these cases, the system will not attempt to contact a payment provider. Validation errors are returned with an HTTP status 400 (Bad Request) and provide human-readable messages under the message property. These messages explain which fields caused the request to fail.

Merchants should review the list of failed validations, correct the request, and resubmit. These errors always occur before the request is sent to the customer's payment provider.

Example – single validation error

{
  "message": "Merchant with key 73afeb45-432e-4b91-be37-a6b3d2fb7447 does not exist"
}

Example – multiple validation errors

{
  "message": [
    {
      "payment": [
        "amount must not be less than 0.01",
        "currencyCode must match /^[A-Z]{3}$/ regular expression",
        "currencyCode must be a string",
        "currencyCode should not be empty"
      ]
    },
    {
      "consumer": [
        "firstName must be shorter than or equal to 60 characters",
        "firstName must be a string",
        "firstName should not be empty"
      ]
    }
  ]
}

info

If you get response codes other than 200 (e.g., 4xx or 5xx) and the paymentStatus did not change to FAILED please retry the operation up to 3 times within 10 minutes and contact Customer Support in case the error persists.

Processing Errors

If your request passes validation but fails during communication with a payment provider or gateway, SmartPay includes an error field in the response. Processing errors contain:

• error – a SmartPay error code that categorizes the issue.
• errorDetails – additional information, often including descriptions returned by the payment provider.
  • gatewayDescription – a high-level message from SmartPay.
  • paymentProviderDescription – a provider-specific explanation, if available.
  • context – raw response data from the provider, useful for troubleshooting.

Example – processing error

{
  "error": "payment_provider_processing",
  "errorDetails": {
    "gatewayDescription": "External payment provider failed to process the operation.",
    "paymentProviderDescription": "Issuer declined the transaction.",
    "context": "<full provider response>"
  }
}

SmartPay includes fields such as gatewayDescription and paymentProviderDescription to provide a human-readable explanation of errors, but these should never be relied upon for structured parsing. They are intended to give you context, not machine-readable categorization. Because the mapping of error codes is not exhaustive across all providers and payment methods, merchants may encounter responses that are not explicitly listed in our documentation. In such cases, the safest approach is to log the full error response for internal troubleshooting. If you are unsure how to interpret and error or how it affects a transaction, please reach out to SmartPay Support for assistance. Our team can help clarify the meaning of uncommon or provider-specific errors and guide you in applying the correct handling in your integration.

The following errors appear in the error and errorDetails fields of the response and usually indicate that the provider was unable to authorize, capture or complete the transaction. The following table lists the most common error codes and their descriptions.

Error code	Description
gateway_processing	The request was rejected by the SmartPay gateway.
payment_provider_processing	The request was rejected by the payment provider.
processing_error	Payment couldn't be processed.
payment_provider_card_blocked	The card is blocked.
payment_provider_card_not_supported	This card type can't be authorized.
payment_provider_card_invalid	Invalid card details.
payment_provider_card_restricted	The card usage has been restricted.
payment_provider_card_stolen	The card has been marked as stolen.
payment_provider_card_expired	The expiry date on the card has passed or is wrong.
payment_provider_card_declined	The card was declined by authorization system.

Example - full processing error response

{
  "transactionId": "5853dbbf-b1a5-4fd6-8d62-7c92a285166f",
  "reconciliationReferenceId": "V82yE6sMxClcR0lrXVmIo",
  "description": "SMP*TRX*Test*01",
  "paymentStatus": "FAILED",
  "creationDate": "2022-07-12T23:44:45.783Z",
  "lastStatusDate": "2022-07-12T23:45:53.238Z",
  "transactionOverview": {
    "amount": 10.50,
    "currencyCode": "EUR",
    "mit": false,
    "transactionId": "5853dbbf-b1a5-4fd6-8d62-7c92a285166f",
    "paymentMethod": "CARDS",
    "customerAccountId": "Test-123"
  },
  "statusHistory": [
    {
      "status": "CREATED",
      "statusDate": "2022-07-12T23:44:45.783Z",
      "modificationAmount": {
        "amount": 10.50,
        "currencyCode": "EUR"
      }
    },
    {
      "status": "AUTHORIZATION_INITIALIZED",
      "statusDate": "2022-07-12T23:45:21.329Z",
      "modificationAmount": {
        "amount": 10.50,
        "currencyCode": "EUR"
      }
    },
    {
      "status": "FAILED",
      "statusDate": "2022-07-12T23:45:53.238Z",
      "modificationAmount": {
        "amount": 10.50,
        "currencyCode": "EUR"
      },
      "error": "payment_provider_processing"
    }
  ],
  "carrierNumber": "hells.butcher_001@mail.com"
}

tip

• Always log the full error response including transactionId, reconciliationReferenceId, error, errorDetails and timestamps.
• Never expose raw error codes or provider details to customers. Show only neutral and customer-friendly messages.
• Use the error codes internally for reconciliation and troubleshooting.
• Validate inputs locally to reduce unnecessary validation errors.
• Retry temporary failures such as timeouts up to 3 times within 10 minutes.
• Contact your Product Solution Specialist if you need assistance interpreting error codes for your integration.