Skip to main content

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

FieldDescriptionType
reconciliationReferenceIdExternal payment provider unique transaction identifier.String
descriptionTransaction description, as specified by you in the checkout API request.String
paymentStatusCurrent status of the initial payment transaction.String, see payment status model
creationDateTransaction creation date and time.String
lastStatusDateTransaction status changing date and time.String
transactionOverviewCollection of initial payment transaction data.Object, see level 2 transaction overview.
modificationsArray of all performed transaction modifications.Array, see level 2 modifications.
info

reconciliationReferenceId:

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 captuered 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.

FieldDescriptionType
transactionIdThe unique identifier of the transaction generated on transaction creation.String
paymentMethodUsed payment option code.Payment option code, see Data model
customerAccountIdUnique customer identifier.String
amountTransaction modification amount.Decimal
currencyCodeTransaction modification currency. The 3-letter currency ISO-4217 code.String
mitFlag to show if created transaction relates to merchant initiated transactions.Boolean
paymentOriginDisplays 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.

FieldDescriptionType
modificationDataAdditional details on the modification.ModificationData
modificationData-typeType of performed transaction modification. Possible values: "CAPTURE", "CANCELLATION", "CHARGEBACK", "SETTLEMENT", "REFUND" according to the respective API methods.String
modificationData-modificationIdYour unique reference for the requested modification.String
modificationData-reconciliationReferenceIdExternal provider unique transaction identifier.String
modificationAmountRequested transaction amount information.Amount
modificationAmount-descriptionDescription provided for the modification.String
modificationAmount-amountTransaction modification amount.Decimal
modificationAmount-currencyCodeTransaction modification currency. The 3-letter currency ISO-4217 code.String
statusActualized transaction or refund status after the performed modification.String
errorError code in case of a failed modification. Please refer to the section "error field" below.String
creationDateModification transaction creation date and time.String
statusHistoryThe 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-statusStatus of the transaction modification or initial payment transaction. Refer to Payment Status.String
statusHistory-statusDateModification transaction status changing date and time.String
statusHistory-modificationAmountRequested transaction amount information.Amount
statusHistory-errorError 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 described above contains a code depending on the nature of the failure. Reason and the the possible values are as defined on the table below.

Case 1. If the errors below occur, contact customer support:

ErrorDescription
gateway_processingRejected by the payment gateway
processing_errorThe payment couldn't be processed
payment_provider_processingRejected by the payment provider

Case 2. In case of the errors below do the following:

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.

ErrorDescription
payment_provider_card_stolenThe card has been marked as stolen
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 wrong
payment_provider_card_blockedThe card is blocked
payment_provider_card_declinedDeclined by the authorization system
important

Please note that the error code 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 activities. 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 a card is flagged as stolen). The "error" field is part of the technical API response as to provide you as a Merchant with the appropriate action to perform for each case.

info

Please check our status model for further information regarding the status transitions.

Success

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

Status Code:

200 (OK)

Header:

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",
"mit": false,
"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

important

Payment provider errors are critical issues which changes the paymentStatus to "FAILED" (e.g., card issuer rejected the transaction due to risk checks). In such cases the transaction cannot be further processed. "FAILED" status for modifications means that only the modification failed, but the transaction might be processed further.

In both cases please log those errors and contact our customer support for further guidance.

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",
"mit": false,
"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

info

Validation errors mainly occur in the integration phase, e.g. if an API is not correctly implemented. They are not logged to the transaction modification log, so it is safe to correct and retry the request.

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"
]
}
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 opteration up to three times within ten minutes and contact customer support in case the error persists.