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
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. |
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.
| 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 |
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: "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 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:
| Error | Description |
|---|---|
| gateway_processing | Rejected by the payment gateway |
| processing_error | The payment couldn't be processed |
| payment_provider_processing | Rejected 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.
| Error | Description |
|---|---|
| payment_provider_card_stolen | The card has been marked as stolen |
| payment_provider_card_restricted | The card usage has been restricted |
| payment_provider_card_not_supported | This card type can't be authorized |
| payment_provider_card_invalid | Invalid card details |
| payment_provider_card_expired | The expiry date is passed or wrong |
| payment_provider_card_blocked | The card is blocked |
| payment_provider_card_declined | Declined by the authorization system |
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.
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
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
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"
]
}
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.