Integration Journey
Authentication
SmartPay solution supports strong API authentication. In order to authenticate within the SmartPay APIs, you will need to provide the standard "Authorization" header in every request. SmartPay supports two authentication schemes in accordance with RFC standard: Basic and Bearer.
Basic Authentication
When Basic authentication scheme is configured, the value to be passed in the header is base64-encoded credentials containing your merchantKey as username and authentication key as password. MerchantKey and authentication key will be provided by your dedicated Product Solutions Specialist.
Header:
Authorization: Basic <base64(merchantKey:authenticationKey)>
Bearer Authentication
In Bearer scheme, first you need authenticate against SmartPay OAuth 2.0 provider with your clientId and clientSecret.
Request
Path:
POST https://smartpay-oauth-cons.auth.eu-central-1.amazoncognito.com/oauth2/token
Header:
Content-Type: application/x-www-form-urlencoded
client_id=<clientId>&client_secret=<clientSecret>&grant_type=client_credentials
OAuth ClientID and ClientSecret will be provided by your dedicated Product Solutions Specialist. Token URL for respective environment can be obtained in the Sandbox vs. Production page.
Response
{
"access_token": "eyJraWQi....Qeg",
"expires_in": 3600,
"token_type": "Bearer"
}
If successfully authenticated, received JWT received in "access_token" parameter should be used in every SmartPay API request as Bearer token.
Header: Authorization: Bearer <access_token>
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 name | Type | Length | Mandatory |
|---|---|---|---|
| X-Access-Token | JWT | 512 | NO |
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.
Specifying the Customer Account ID as part of the Create Checkout API call indicates to SmartPay that the transaction in question should be processed using a payment credential vault. If one does not exist, it is created, where it exists any persisted (tokenized) payment options are retrieved and shown in the widget.
We recommend setting a minimum timeout of 90 seconds, even though the API requests are expected to return a response much faster.
Process Flow
- Your server initializes a new payment, requesting a Transaction ID and Checkout Token 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 authorizes the request.
- Your server forwards the Checkout Token to your client for initialization of the SmartPay Widget.
- 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.
- Your client triggers your server to verify whether the payment was successful, based on the JavaScript callback.
- Your backend calls SmartPay API method Get Payment Status verifies the transaction status by providing Transaction ID received in step 1.
Create Checkout
The complete checkout process utilizes the single API request Create Checkout with the following structure.
Sample below shows checkout for a guest payment credit card transaction. Please refer to our API documentation for full explanation of this API method.
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"
}
}
The Create Checkout response includes the 36-character GUID of the transaction-ID which can be used for further modification and status APIs and 512 bits checkout token required for front-end widget rendering.
Response
{
"transactionId": "fc10f767-12a7-46d0-9da0-4af6b5b67c4d",
"checkoutToken": "KwlJmj1QoJL4oFPaCYnNCTW8cC8ZsLvQg16erCzx7hlU0rxLi3TdAKBLAN6md2Ik",
"paymentStatus": "CREATED",
"requestTime": "2023-04-05T13:25:41.790Z"
}
The transactionId and checkoutToken should be associated and persisted with any given business transaction within the integrated solution, e.g. paying for the goods in a shopping cart during checkout may have one or more transactionId and checkoutToken pairs associated with it as a user attempts to pay using different payment options. This should be accessible to support staff and initially testers to submit any service requests relating to the integration process to help speed up the analysis.
Render SmartPay Widget
Our SmartPay SDKs are made up of light-weight libraries which allow to securely collect payment option details. This approach 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.
Web Checkout
Mobile Checkout
Documentation can be found here:
Mobile checkout is currently in beta phase. If you are interested to use our native iOS / Android SDKs, please reach out to your Product Solutions Specialist.
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",
"mit": false,
"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.