Integration

Last changes: 10-07-2020

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 associate 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 the Payment Status via a JavaScript callback once finished.
     
  4. Your client triggers your server to verify whether the payment was successful based on the JavaScript callback (triggered through the registerPaymentCompletedHandler or registerErrorHandler).
     
  5. Your server by calling the SmartPay API method Get Payment Transaction Status 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": "3227a1df-1033-46fd-93bd-x01777339e5b",
    "customerAccountId": "CUST-000001",
    "payment": {
        "amount": 2000.01,
        "currencyCode": "EUR",
        "description": "Purchase 1x product ABC"
    },
    "billingAddress": {
        "customerFullName": "Jacob Smith",
        "emailAddress": "customer@example.com",
        "address": "Anystreet",
        "number": "123",
        "city": "Anycity",
        "postCode": "12345",
        "countryCode": "DE"
    }
}

Response

{
    "transactionId": "4e687bcc-053d-47e1-ad15-ae0c30a41d03",
    "paymentStatus": "CREATED"
}

Render Payment Form

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.

Mobile Checkout

Get Payment Transaction Status

The Widget returns the result of the submitted payment via a callback (e.g. the Javascript callbacks registerErrorHandler & registerPaymentCompletedHandler in case of the Web SDK) to your client. 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/transaction/4e687bcc-053d-47e1-ad15-ae0c30a41d03

Header:

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

Response

{
    "paymentTransaction": {
        "originDomain": "https://localhost.localdomain",
        "channelResult": {...},
        "uniqueReference": "avxC18sXLkOyLvamfqNqFQ",
        "billingAddress": {...},
        "creationDate": "2020-03-05T17:54:51.179Z",
        "TTL": 1586022891,
        "channel": {...},
        "merchant": {...},
        "fspayResponses": [
            {
                "dateUTC": "2020-03-05",
                "timeUTC": "175536",
                "operation": "INIT_AUTHORIZE",
                "responseDescription": "Successful execution.",
                "statusCode": "RECEIVED",
                "responseCode": "0000"
            },
            {
                "dateUTC": "2020-03-05",
                "timeUTC": "175552",
                "operation": "COMPLETE_AUTHORIZE",
                "responseDescription": "Successful execution.",
                "statusCode": "AUTHORIZED",
                "responseCode": "0000"
            },
            {
                "dateUTC": "2020-03-05",
                "timeUTC": "175553",
                "operation": "CAPTURE",
                "responseDescription": "Successful execution.",
                "statusCode": "CAPTURED",
                "responseCode": "0000"
            }
        ],
        "paymentStatus": "CAPTURED",
        "payment": {
            "description": "TXL Parking Airport ABA80m7dRF",
            "amount": 3.99,
            "currencyCode": "EUR",
            "option": "VISA"
        },
        "authorizationToken": "aHR0cHM6Ly93cHAtdGVzdC53aXJlY2FyZC5jb20vc2VhbWxlc3M/d1BheW1lbnRUb2tlbj1nbHpfbVVKSDVWbUZLYVNlVmFzdm9pRndLa2sxMWM4NlFtY2xwbFpXaTFj",
        "id": "4e687bcc-053d-47e1-ad15-ae0c30a41d03",
        "paymentStatusAndDate": "SESSION_COMPLETED@2020-03-05T17:55:53.722Z"
    }
}

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)

Where this is not the case, please log/store in your administrative/support console the following response parameter values for later analysis:

  • uniqueReference
  • creationDate
  • fspayResponses (array contents)
  • paymentStatus
  • authorizationToken
  • id