Hosted Page

POST {CORE_URL_ISSUED_BY_PAYTIKO}/api/payment/hosted-page

Headers

Name	Type	Description
Content-Type*	String	application/json
X-Merchant-Secret*	String	{MERCHANT_SECRET_KEY_ISSUED_BY_PAYTIKO}

Request Body

Name	Type	Description
timestamp*	String	Unix Epoch timestamp.
signature*	String	$rawSignature = `${billingDetails.email};${timestamp};${MERCHANT_SECRET_KEY_ISSUED_BY_PAYTIKO}` $signature = SHA256($rawSignature)
webhookUrl	String	Webhook notification URL.
successRedirectUrl	String	URL where client will be redirectied when payment is successful.
failedRedirectUrl	String	URL where client will be redirectied when payment is failed.
billingDetails.firstName*	String	First Name (or full name if last name cannot be provided).
billingDetails.lastName	String	Last Name.
billingDetails.email*	String	Unique client e-mail.
billingDetails.street	String	Street.
billingDetails.region	String	Region.
billingDetails.city	String	City.
billingDetails.country*	String	2-chars country code. (ISO 3166-1 alpha-2).
billingDetails.zipCode	String	ZIP / Postal Code.
billingDetails.phone*	String	Phone number.
billingDetails.dateOfBirth	String	Date of birth. Format: YYYY-MM-dd
billingDetails.gender	String	[ 'Male', 'Female' ]
billingDetails.currency*	String	3-chars currency code (ISO 4217).
orderId*	String	Your internal unique order identifier. Used to identify your order and update it on webhooks.
disabledPspIds	Array	Ids of payment processors which should be disabled in the cashier. Ex: [12321, 54455, 34212]
creditCardOnly	Boolean	This parameter is used to show only credit card processors in the payment widget.
billingDetails.lockedAmount	Numeric	Widget-locked amount value.
cashierDescription	String	Text shown in the cashier as an order description. (Max length is 1024 characters)
isPayOut	Boolean	Activates cashier in payout mode.

200: OK

{
    "redirectUrl": "https://{CASHIER_HOST}?sessionToken=hp-b8fc5a8f-ce0b-49ab-a027-a1d05cc5c7a3&m_orderId=7f00853a-03de-4605-bb3f-f16ab9510fe1"
}

400: Bad Request

{
    "errors": {
        "MerchantId": [
            "Property is required. Path 'billingDetails.email', line 1, position 1."
        ]
    },
    "title": "One or more validation errors occurred.",
    "status": 400
}

Additional query parameters

You can supply additional query parameters to adjust your widget visualization.

The complete redirect URL looks as the follows:

https://{CASHIER_HOST}?sessionToken=hp-b8fc5a8f-ce0b-49ab-a027-a1d05cc5c7a3&m_orderId=7f00853a-03de-4605-bb3f-f16ab9510fe1&m_fixed_pp_id=14854

Full list of query parameters presented below:

Query Parameter	Type	Description
m_fixed_pp_id	numeric	Fixed payment processor identifier. Only this processor will be shown within the current cashier session.

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

Request body example

{
    "timestamp": "1669923838",
    "orderId": '3aa1e912-6ff3-4925-82dc-66bd7927676c',
    "signature": "gJTYTtv4MO6TNDBfBETz/V2hiXoDgVe5vKKenLITj18=",
    "webhookUrl": "http://your-api-url.com/webkook",
    "successRedirectUrl": "https://your-site-url.com/success",
    "failedRedirectUrl": "https://your-site-url.com/failed",
    "billingDetails": 
    {
        "firstName": "TestName",
        "lastName": "TestLastName",
        "email": "[e-mail]",
        "street": "Khreshatyk street",
        "region": "Kyiv",
        "city": "Kyiv",
        "phone": "[phone]",
        "zipCode": "01001",
        "country": "UA",
        "dateOfBirth": "1990-03-15",
        "currency": "USD"
    }
}

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 request body sample

{
    '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': '[e-mail]', // 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': '[phone]' // 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}`)