Skip to main content

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

FieldMandatoryDescriptionTypeLength
transactionIdYesThe Transaction ID received by calling the SmartPay API method Create Checkout.GUID36

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 }

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.
paymentLinkIdIn case the payment transaction was created via payment link, indicates the identifier of the corresponding payment link object.String
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 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.

FieldDescriptionType
transactionIdThe unique identifier of the transaction generated on transaction creation.String
mitFlag to show if created transaction relates to merchant initiated transactions.Boolean
amountTransaction modification amount.Decimal
currencyCodeTransaction modification currency. The 3-letter currency ISO-4217 code.String
paymentMethodUsed payment option code.Payment option code, see Data model
customerAccountIdUnique customer identifier.String
customReferencesFor external party usagecustomReferences
dealDetails of the deal. Used only for 3RI payments (Split and Delayed shipment workflows).Deal, see Data model
targetMerchantAccountReferenceIf provided, the payment is processed in favour of the indicated submerchant account, and the main merchant account number is ignored.String
paymentOriginDisplays the origin flag marked upon creation of the transaction.Enumeration that can be of value:
  • HOSTED_PAYMENT_PAGE
  • CHECKOUT
  • PAYMENT_AUTHORIZE_S2S
  • SUBSCRIPTION_MIT
  • MERCHANT_MIT
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-modificationIdMerchant unique request identifier - as sent by you in the modification API request.String
modificationData-reconciliationReferenceIdExternal provider unique transaction identifier.String
modificationData-customReferencesA 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
modificationAmountRequested transaction amount information.Amount
modificationAmount-amountTransaction modification amount.Decimal
modificationAmount-currencyCodeTransaction modification currency. The 3-letter currency ISO-4217 code.String
statusLast status of the transaction modification or initial payment transaction. Refer to Payment Status.String
errorError code in case of a failure.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 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"
}