Integration Journey

Last changes: 09-12-2022

Authentication

SmartPay solution supports strong API authentication. Thus, in order to authenticate within the SmartPay APIs, basic authorisation header is to be provided, using:

  • Username: being your merchantKey 
  • Password: key provided

 (merchantKey & Passwords shall be provided by your dedicated Technical Rollout Manager).

Custom headers

IDKit token

Identity Kit token authentication is supported in SmartPay APIs.
This is an optional header, and if sent in the API request, it shall be as per the below:

Header nameTypeLengthMandatory
X-Access-TokenJWT512NO

Guest Payment

Guest payments enable end users to provide their payment option details for each payment i.e. the payment option is not persisted (tokenized) and not associated with an account.

Payment Credential Vault Based Payment

Payment Credential Vault based payments enable end users to persist (tokenize) their provided payment option details so that these can be re-used without needing to be entered as part of future payments.

Process Flow

  1. Your server initializes a new payment, requesting a Transaction ID by calling the SmartPay API method Create Checkout for a one off guest payment without the Customer Account ID specified or where provided for an existing or new customer, alongside your secret Merchant Key which authenticates the request.
     
  2. Your server forwards the Transaction ID to your client for initialization of the SmartPay Widget.
     
  3. The customer securely submits their payment information via the initialized SmartPay Widget which directly communicates to the acquirer and provides a JavaScript callback once finished.
     
  4. Your client triggers your server to verify whether the payment was successful, based on the JavaScript callback, by calling the SmartPay API method Get Payment Status and verifies the transaction status.

Create Checkout

The complete checkout process utilizes the single API request Create Checkout with the following structure.

Request

Path:

POST {Base URL}/payment/creation

Header:

Content-Type: application/json
Accept-Language: en-US

{
    "merchantKey": "48c4e923-e88c-464b-a4e7-ccb2c6d3775e",
    "payment": {
        "amount": 10.99,
        "currencyCode": "EUR",
        "description": "Purchase 1x product ABC"
    },
    "consumer": {
        "firstName": "Butcher", 
        "lastName": "Hells",       
        "emailAddress": "hells.butcher_001@mail.com",
    },
    "billingAddress": {,
        "addressLine1": "Anystreet",
        "number": "123",
        "city": "Anycity",
        "postCode": "12345",
        "countryCode": "DE"
    }
}

Response

{
    "transactionId": "48c4e923-e88c-464b-a4e7-ccb2c6d3775e",
    "paymentStatus": "CREATED",
    "requestTime": "2020-12-15T13:49:36.556Z"
}

Render SmartPay Widget

Our SmartPay SDKs are made up of light-weight libraries which allow to securely collect payment option details. This appraoch maintains a SAQ-A compliant payment-form solution while enabling you to build forward compatible web or mobile experiences which seamlessly combine your corporate identity with the required functionalities whilst adding some additional ancillary functions to ease integration. Our SmartPay SDK supports both single and multipage web sites design techniques.

Mobile Checkout

Documenation can be found here:

Get Payment Transaction Status

The Widget returns you the result of the submitted payment via successHandler or errorHandler javascript callbacks. This should be the trigger for your server (backend) to call the SmartPay API method Get Payment Status to verify the status of the transaction as depicted in the example below.

Request

Path:

GET {Base URL}/payment/status/48c4e923-e88c-464b-a4e7-ccb2c6d3775e

Header:

Content-Type: application/json
Accept-Language: en-US

Response

{
    "transactionId": "48c4e923-e88c-464b-a4e7-ccb2c6d3775e",
    "reconciliationReferenceId": "zKZhOVjJitCdHdJzicGmI",
    "description": "Purchase 1x product ABC",
    "paymentStatus": "CAPTURED",
    "creationDate": "2020-12-15T13:49:36.556Z",
    "transactionOverview": {
        "amount": 10.99,
        "currencyCode": "EUR",
        "transactionId": "48c4e923-e88c-464b-a4e7-ccb2c6d3775e",
        "paymentMethod": "CARDS",
    },
    "modifications": []
}

Evaluate the response parameter "paymentStatus" which should be:

  • "AUTHORIZATION_COMPLETED" if the transaction was successfully authorized (auto-capture = off or delayed)
  • "CAPTURED" if the transaction was successfully captured (auto-capture = on or capture API called)
  • "AUTHORIZATION_PENDING" or "CAPTURE_PENDING" if it the was not synchronously completed

Where this is not the case, please log/store in your administrative/support console the full response for later analysis.

Our customer support especially requires:

  • transactionId
  • reconciliationReferenceId
  • paymentStatus
  • creationDate

Please note: "PENDING" states may occur if the payment provider is not supporting synchronous processing (currently only PayU) or if a payment provider is not responding in time. In such cases, SmartPay automatically attempts to retrieve the final confirmation from the payment provider, so that the pending state will be resolved in a timely manner. If you receive a "PENDING" status retry the get payment status call up to three times within 3 minutes and log an error if the status is not changed.    

Document version 2.0 - 2020-12-17