Web SDK

Web SDK developed to connect your merchant to Paytiko.

Payment Checkout

You need to create a checkout request from your server side providing payment client's billing details. In a successful scenario, the response body will contain cashier session token to proceed a payment on your front-end.

Try out our API Collections

API Collections

Initial checkout request

POST {CORE_URL_ISSUED_BY_PAYTIKO}/api/sdk/checkout

Headers

Name

Type

Description

X-Merchant-Secret*

String

{MERCHANT_SECRET_KEY_ISSUED_BY_PAYTIKO}

Accept*

String

*/*

Accept-Encoding*

String

gzip, deflate, br

Content-Type*

String

application/json; charset=utf-8

User-Agent*

String

SDK API

Request Body

Name

Type

Description

firstName*

String

First name (or full name if last name cannot be provided).

lastName

String

Last name.

email*

String

Unique client e-mail.

currency*

String

3-chars currency code (ISO 4217).

countryCode*

String

2-chars country code. (ISO 3166-1 alpha-2).

orderId*

String

Your internal unique order identifier. Used to identify your order and update it on webhooks.

lockedAmount

Numeric

Locked amount value. If not provided - amount can be changed by client.

phone*

String

Phone number.

city

String

City.

street

String

Street.

region

String

Region.

zipCode

String

ZIP / Postal Code.

dateOfBirth

String

Date of birth.

Format: MM/dd/yyyy

signature*

String

$rawSignature = `${email};${timestamp};${MERCHANT_SECRET_KEY_ISSUED_BY_PAYTIKO}`

$signature = SHA256($rawSignature)

timestamp*

Int64

Unix Epoch timestamp.

gender

String

[ 'Male', 'Female' ]

disabledPspIds

Array

Ids of payment processors which should be disabled in the cashier. Ex: [12321, 54455, 34212]

isPayOut

Boolean

Activates cashier in payout mode.

cashierDescription

String

Text shown in the cashier as an order description. (Max length is 1024 characters)

useEventBasedRedirects

bool

This flag indicates whether the cashier avoids forcing browser redirects and instead uses JavaScript events to track user actions or trigger merchant-side popups. See https://paytiko.gitbook.io/docs/solutions/web-sdk/widget-js-events (paytiko.status-raise event type).

{
    'cashierSessionToken': '69ea4d4d-e8c4-40b1-9c5b-24e4ff76a970'
}

{
    "errorMessage": "The `email` field is required."
}

{
    "ForbiddenByAcl": true
}

"Phone", "City", "Street", "Region" & "ZipCode" fields are not required on our side, but Credit Card solutions have them as mandatory. Leaving these parameters empty may cause errors on PSP side and deposits will be failed.

Request body sample

{
    'firstName': 'John',
    'lastName': 'Doe',
    'email': 'john@doe.com',
    'countryCode': 'GB',
    'currency': 'GBP',
    'lockedAmount': 12.7,
    'orderId': '3834634f-e025-4939-b6e3-7dbb2478249f',
    'phone': '+44839958434',
    'city': 'London',
    'street': 'Baker Str. 12',
    'region': 'London',
    'zipCode': '5123',
    'dateOfBirth': '12/16/1990',
    'signature': 'Iec0DC3zkEsWlPzTjFFfe1K..2qqtPntyjtc6pCwCuTEI=',
    'isPayout': false,
    'timestamp': 1671532725
}

Cashier Visualizaton

<!DOCTYPE html>
<html>
    <head>
        <title>Paytiko Cashier</title>
        <script src="https://core.paytiko.com/cdn/js/sdk/paytiko-sdk.1.0.min.js"></script>
    </head>
    <body>
        <div id="cashier-iframe-container">
            <!-- Cashier will be mounted right here. Iframe default CSS class is `.paytiko-iframe`. -->
    	</div>
        <script>
            const SESSION_TOKEN = '87d2029d-923d-41b5-b852-0bf5b2561726'; // Received on checkout.
            const IFRAME_CONTAINER_SELECTOR = 'div#cashier-iframe-container'
            const DISPLAY_MODE = PAYTIKO_CASHIER_DISPLAY_MODE.IFRAME;
            const LOCALE = 'en-US';
            const ORDER_ID = '3aa1e912-6ff3-4925-82dc-66bd7927676c';

            PaytikoSdk.cashier.invoke({
                environment: 'UAT',
                orderId: ORDER_ID,
                sessionToken: SESSION_TOKEN,
                iframeContainerSelector: IFRAME_CONTAINER_SELECTOR,
                displayMode: DISPLAY_MODE,
                locale: LOCALE
            });
        </script>
    </body>
</html>

`PaytikoSdk.cashier.invoke({})` parameters

Name

Description

Type

Default Value

Required

environment

Environment [UAT, PRODUCTION]. You need to use UAT for development and testing.

string

PRODUCTION

⨉

orderId

Your internal unique order identifier. Used to identify your order and update it on webhooks.

string

✓

sessionToken

Cashier session token received after checkout request.

string

✓

iframeContainerSelector

CSS selector of a desired iframe container. Cashier will be mounted there.

string

✓ If PAYTIKO_CASHIER_DISPLAY_MODE.IFRAME ⨉ If !PAYTIKO_CASHIER_DISPLAY_MODE.IFRAME

displayMode

Required display mode. PAYTIKO_CASHIER_DISPLAY_MODE.IFRAME - Cashier shown as iframe within a required container (default if not specified). PAYTIKO_CASHIER_DISPLAY_MODE.REDIRECT - Cashier shown as a page in the current tab. PAYTIKO_CASHIER_DISPLAY_MODE.REDIRECT_NEW_TAB - Cashier shown as a page in a new tab.

enum

PAYTIKO_CASHIER_DISPLAY_MODE.IFRAME

⨉

locale

Cashier locale.

string

en-US

⨉

autoGenerateOrder

Flag used to automatically generate order identifier if not provided.

boolean

false

⨉

lockCardHolderName

Indicates whether Card Holder Name field is locked (readonly).

boolean

false

⨉

fixedPaymentProcessorId

Fixed payment processor identifier. Only this processor will be shown within the current cashier session. Works for APMs only.

numeric

⨉

creditCardOnly

This parameter is used to show only credit card processors in the payment widget.

boolean

false

⨉

Webhook Control

To receive order status updates from us, you need to expose an open API endpoint (HTTP POST) and share with us this endpoint URL. We resend this webhook to your server with exponential interval until your response status code won't be 200.

Webhook Transaction Statuses

On webhook receiving, the current transaction status reflects the latest payment result by your order ID. The statuses listed earlier in this document describe the possible outcomes based on various payment scenarios.

Success - The payment was processed successfully.
Rejected - The payment was declined by the payment processor (e.g., insufficient funds, card issues).
Failed - The transaction could not be processed due to network issues, payment service provider (PSP) unavailability, or configuration issues.
SubscriptionCancelled - The recurring process was manually cancelled in the CRM.

Webhook request body sample

{
    'Action': "TRANSACTION_DATA_UPDATE",
    'ActionId': "34d3e8a5-c9ad-4553-a940-00e8bc025720", // Webhook corellation action ID.
    'OrderId': '3aa1e912-6ff3-4925-82dc-66bd7927676c', // Merchant Order ID.
    'AccountId': 'c6aad9e8-4fe6-4895b82-cc1ea66b4aad', // Account Unique Identitier.
    'AccountDetails': { // Payer Account Details.
        'MerchantId': 20115, // Merchant Identifier.
        'CreatedDate': '2022-07-18T10:18:31.67087+00:00', // Payer Account Creation Date.
        'FirstName': 'John', // First Name.
        'LastName': 'Doe', // Last Name.
        'Email': 'john@doe.com', // Email.
        'Currency': 'GBP', // ISO Currency Code.
        'Country': 'GB', // ISO Country Code.
        'Dob': '12/16/1990', // Date of Birth.
        'City': 'London', // City.
        'ZipCode': '5123', // Postal Code.
        'Region': 'London', // Region.
        'Street': 'Baker Str. 12', // Street.
        'Phone': '+44839958434' // Phone.
     },
     'TransactionType': 'PayIn' // PayIn / PayOut / Refund.
     'TransactionStatus': 'Success', // Success / Rejected/ Failed.
     'InitialAmount': 12.58, // Order price.
     'Currency': 'EUR', // Payment currency.
     'TransactionId': 179411, // Internal transaction ID.
     'ExternalTransactionId': '63793736354518895200', // External transaction ID.
     'PaymentProcessor': 'World Pay', // Payment processor name.
     'DeclineReasonText': null, // Processing error description.
     'CardType': 'Visa', // Visa, MasterCard, AMEX, JCB, UnionPayChina, Discover, DinersClub, MIR.
     'LastCcDigits': '5432', // Last 4 digits of CC number.
     'CascadingInfo': { // Cascading history (for CC payment systems only).
         'SessionId': '6908d8cf-06e6-4121-9969-3791aa77ace3',
         'AttemptsVector': [
            { // First attempt.
              'PaymentSystem": 'Safe Charge',
              'PaymentProcessorId': 50133,
              'PaymentProcessorKey': 'ad6335b8-7f52-45d7-81fb-11e5f81bc7f5',
              'DeclineReason': 'Acquirer Validation',
              'ExternalTransactionId': '63814313373237072733',
              'InternalPspId': '711000000021055202',
              'TransactionId': 400854,
              'Date': '2023-03-13T14:09:33.2372322+00:00',
              'Status': 'Rejected'
            },
            { // Last attempt.
              'PaymentSystem": 'World Pay',
              'PaymentProcessorId': 50590,
              'PaymentProcessorKey': '1f052a08-7aeb-442c-aeed-b4040898d423',
              'DeclineReason': null,
              'ExternalTransactionId': '63793736354518895200',
              'InternalPspId': '5456650000021055202',
              'TransactionId': 179411,
              'Date': '2023-03-13T14:12:33.2372322+00:00',
              'Status': 'Success'
            }
        ]
    },
    'IssueDate': "2023-03-13T14:12:33.2372322+00:00", // UTC+0 Webhook Issue date.
    'InternalPspId': '5456650000021055202', // Payment gateway's transaction unique ID.
    'MaskedPan': "455636******5432" // Masked credit card number for CC processors.
    'Signature': 'Xrg3DzkEsWlPzTjFFfe1K..7qqtPntyjtc6pCwCuTDY='
}

Webhook signature generated as:
$signature = SHA256(`${MERCHANT_SECRET_KEY_ISSUED_BY_PAYTIKO}:${orderId}`)

PreviousChange log NextAPI Collections

Last updated 12 days ago

Was this helpful?

Payment Checkout

Initial checkout request

Headers

Request Body

Cashier Visualizaton

PaytikoSdk.cashier.invoke({}) parameters

Webhook Control

`PaytikoSdk.cashier.invoke({})` parameters