Get Payment Status API
The API method Get Payment Status returns the payment status and the status and history of any modification initiated by you.
API Request Parameters
| Field | Mandatory | Description | Type | Length |
|---|---|---|---|---|
| transactionId | Yes | The Transaction ID received by calling the SmartPay API method Create Checkout. | GUID | 36 |
Request
Specify the transaction-ID in the URL.
Path:
GET {Base URL}/payment/status/aeaabe56-3c05-44fb-9f19-9f27074ef5a4
The request must have the following headers:
- Content-Type:
application/json - Accept-Language:
en-US - Origin:
{ Origin } - User-Agent:
{ User-Agent }
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. |
| paymentLinkId | In case the payment transaction was created via payment link, indicates the identifier of the corresponding payment link object. | String |
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 |
| mit | Flag to show if created transaction relates to merchant initiated transactions. | Boolean |
| amount | Transaction modification amount. | Decimal |
| currencyCode | Transaction modification currency. The 3-letter currency ISO-4217 code. | String |
| paymentMethod | Used payment option code. | Payment option code, see Data model |
| customerAccountId | Unique customer identifier. | String |
| customReferences | For external party usage | customReferences |
| deal | Details of the deal. Used only for 3RI payments (Split and Delayed shipment workflows). | Deal, see Data model |
| targetMerchantAccountReference | If provided, the payment is processed in favour of the indicated submerchant account, and the main merchant account number is ignored. | String |
| paymentOrigin | Displays the origin flag marked upon creation of the transaction. | Enumeration that can be of value:
|
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 |
| modificationData-customReferences | A list of custom references submitted by the merchant along with a modification request (e.g. Capture, Cancel, Refund). Can be different from the customReference value provided in the Create Checkout API. | Custom references, check Data model |
| 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 |
Response sample #1
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",
"mit": false,
"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"
}
}
]
}
]
}
Response sample #2
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",
"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.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"
}
Response sample #3
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": "MPS*SMARTPAY*01BA",
"paymentStatus": "CAPTURED",
"creationDate": "2023-04-17T10:32:56.409Z",
"lastStatusDate": "2023-04-17T10:33:06.162Z",
"transactionOverview": {
"amount": 800,
"currencyCode": "EUR",
"mit": false,
"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": "MPS*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"
}