The request must have the following headers:
Content-Type: application/json
Accept-Language: en-US
Origin: { Origin }
Get Payment Status API
Last changes: 09-04-2023
The API method Get Payment Status returns the payment status and the status and history of any modification initiated by you.
| Field | Mandatory | Description | Type | Length |
| transactionId | Yes | The Transaction ID received by calling the SmartPay API method Create Checkout. | GUID | 36 |
-
Path:
-
GET {Base URL}/payment/status/aeaabe56-3c05-44fb-9f19-9f27074ef5a4
-
Header:
-
Content-Type: application/json
Accept-Language: en-US
Error exposing disclamer
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 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 |
| customReferences | For external party usage | customReferences |
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 | Merchant unique request identifier - as sent by you in the modification API request. | String |
| modificationData-reconciliationReferenceId | External provider unique transaction identifier. | String |
| modificationAmount | Requested transaction amount information. | Amount |
| modificationAmount-amount | Transaction modification amount. | Decimal |
| modificationAmount-currencyCode | Transaction modification currency. The 3-letter currency ISO-4217 code. | String |
| status | Last status of the transaction modification or initial payment transaction. Refer to Payment Status. | String |
| error | Error code in case of a failure. | 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 failure. | String |
Please refer to this section for the possible values of the field "error", as well as the actions to be taken for each type.
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
{
"partnerReference": "InternalTRX_ID00001",
"reconciliationReferenceId": "pzFdwq0ImRFYGYuq41xCH",
"description": "Test-transaction-1234",
"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"
},
"modifications": [
{
"modificationData": {
"type": "CAPTURE",
"modificationId": "jhgjhabkjh58gjgkjhlkjkhgkjhg6",
"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",
"reconciliationReferenceId": "FJ9wbkRjJZsRYCrjgaGGY",
},
"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"
}
}
]
}
]
}The sample below shows a checkout with failed authorization.
200 (OK)
Content-Type: application/json
{
"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.5,
"currencyCode": "EUR",
"transactionId": "5853dbbf-b1a5-4fd6-8d62-7c92a285166f",
"paymentMethod": "CARDS",
"customerAccountId": "Test-123"
},
"statusHistory": [
{
"status": "CREATED",
"statusDate": "2022-07-12T23:44:45.783Z",
"modificationAmount": {
"amount": 10.5,
"currencyCode": "EUR"
}
},
{
"status": "AUTHORIZATION_INITIALIZED",
"statusDate": "2022-07-12T23:45:21.329Z",
"modificationAmount": {
"amount": 10.5,
"currencyCode": "EUR"
}
},
{
"status": "FAILED",
"statusDate": "2022-07-12T23:45:53.238Z",
"modificationAmount": {
"amount": 10.5,
"currencyCode": "EUR"
},
"error": "payment_provider_processing"
}
],
"carrierNumber": "hells.butcher_001@mail.com"
}The sample below shows a checkout with auto-capture, via 'Pre-payment' as a payment option, and so the "transactionReference" field is returned as part of the response.
The "transactionReference" is the transaction identifier, that must be used by the end-customer, as a reference/usage (Verwendungszweck), while initiating their bank transfer.
200 (OK)
Content-Type: application/json
{
"reconciliationReferenceId": "JLiSXwLBvI82ffamzIUXm",
"description": "VWFS*SMARTPAY*01BA",
"paymentStatus": "CAPTURED",
"creationDate": "2023-04-17T10:32:56.409Z",
"lastStatusDate": "2023-04-17T10:33:06.162Z",
"transactionOverview": {
"amount": 800,
"currencyCode": "EUR",
"transactionId": "e92dbc89-ce39-41cd-a6ad-721154b3e379",
"paymentMethod": "PREPMNT",
"customerAccountId": "test6gN4aJIR7B"
},
"modifications": [
{
"modificationData": {
"type": "CAPTURE",
"modificationId": "e92dbc89-ce39-41cd-a6ad-721154b3e379",
"reconciliationReferenceId": "JLiSXwLBvI82ffamzIUXm"
},
"modificationAmount": {
"amount": 800,
"currencyCode": "EUR",
"description": "VWFS*SMARTPAY*01BA"
},
"status": "CAPTURED",
"creationDate": "2023-04-17T10:33:05.815Z",
"lastStatusDate": "2023-04-17T10:33:06.162Z",
"statusHistory": [
{
"status": "CAPTURE_PENDING",
"statusDate": "2023-04-17T10:33:05.815Z",
"modificationAmount": {
"amount": 800,
"currencyCode": "EUR"
}
},
{
"status": "CAPTURED",
"statusDate": "2023-04-17T10:33:06.162Z",
"modificationAmount": {
"amount": 800,
"currencyCode": "EUR"
}
}
]
}
],
"statusHistory": [
{
"status": "CREATED",
"statusDate": "2023-04-17T10:32:56.409Z",
"modificationAmount": {
"amount": 800,
"currencyCode": "EUR"
}
},
{
"status": "AUTHORIZATION_INITIALIZED",
"statusDate": "2023-04-17T10:33:04.228Z",
"modificationAmount": {
"amount": 800,
"currencyCode": "EUR"
}
},
{
"status": "AUTHORIZATION_COMPLETED",
"statusDate": "2023-04-17T10:33:05.729Z",
"modificationAmount": {
"amount": 800,
"currencyCode": "EUR"
}
},
{
"status": "CAPTURE_PENDING",
"statusDate": "2023-04-17T10:33:05.815Z",
"modificationAmount": {
"amount": 800,
"currencyCode": "EUR"
}
},
{
"status": "CAPTURED",
"statusDate": "2023-04-17T10:33:06.162Z",
"modificationAmount": {
"amount": 800,
"currencyCode": "EUR"
}
}
],
"transactionReference": "116352713196042"
}Document version 2.3 - 2023-04-17 - Response sample #3 has been added.
Document version 2.2 - 2021-01-28 - note regarding CARDS payment option code added.
Document version 2.1 - 2021-01-04 (Minor correction to response sample and reconciliationReferenceID description)