Direct Payment API

Feature which allows merchants to create direct checkouts getting rid of the Paytiko widget but use their own user interface.

Service Description

The Direct Payment API provides a robust mechanism for processing both credit and debit card transactions directly through a RESTful API. This system enables merchants to handle card data collection internally, offering a streamlined and secure checkout experience.

Prerequisites

To begin using the Direct Payment API, clients must first obtain the necessary API credentials. These credentials are essential for authenticating with the API and securing communication.

The steps to obtain API credentials presented below:

1. Contact Paytiko: Reach out to your Paytiko account manager to request access to the API.

2. Receive Credentials: Once your request has been reviewed and approved, you will receive your API credentials, including a user name and secret password. Keep these credentials secure and do not share them publicly.

Going to Production

Before going to production, the merchant must complete the PCI DSS Self-Assessment Questionnaire A (SAQ-A) and provide AOC (Attestation of Compliance) document to Paytiko.

This requirement exists because, in cases where the payment is integrated through the Direct API (i.e., the payment form is hosted on the merchant’s website), there is a risk that credit card data could be exposed or compromised directly from the merchant’s environment. Even if the data is intended to be passed securely to the payment processor, having the payment form on the merchant's site means the site technically handles sensitive cardholder information—making it a potential point of vulnerability.

To ensure compliance with the Payment Card Industry Data Security Standard (PCI DSS) and to protect customer data, merchants using such integrations must demonstrate that they meet the relevant security requirements outlined in SAQ-A. This includes confirming that their systems are properly secured and that no sensitive credit card data is stored, processed, or transmitted improperly.

Completing SAQ-A is not just a checkbox—it's a necessary step to reduce the risk of data breaches and build trust with customers.

API Endpoints

Authentication

Once you have your API credentials, you will need to exchange them for a JWT (JSON Web Token) to make authenticated API calls. This token is temporary and expires in 720 seconds (12 minutes), after which you will need to re-authenticate.

POST {API_URL_ISSUED_BY_PAYTIKO}/api/direct-payment/v1/auth

Headers

Name	Value	Required
Content-Type*	application/json

Body

Name	Type	Description	Required
userName*	string	User name.
password*	string	Secret password.

Response

200: OK

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1...",
    "expiresIn": 720
}

401: Unauthorized

{
    "title": "Unauthorized",
    "traceId": "00-73c6f1d4f1b49396c894479ba2cea554-965237ccc270a7c5-00"
}

400: Bad Request

{
    "title": "One or more validation errors occurred.",
    "errors": {
        "userName": [
            "Property is required. Path 'UserName', line 1, position 1."
        ]
    }
}

Get Payment Processor Targets

GET {API_URL_ISSUED_BY_PAYTIKO}/api/direct-payment/v1/payment/checkout/payment-processors

Get available payment processor targets against which checkout is possible for the current merchant.

Headers

Name	Value	Required
Authorization*	Bearer <token>

Response

200: OK

{
  "items": [
    {
      "id": 50312,
      "title": "Emerchant Pay",
      "paymentSystem": "EmerchantPay",
      "isCreditCard": true
    },
    {
      "id": 50328,
      "title": "Astropay",
      "paymentSystem": "Astropay",
      "isCreditCard": false
    }
  ]
}

401: Unauthorized

Unauthorized.

Get Billing Fields By Processor

GET {API_URL_ISSUED_BY_PAYTIKO}/api/direct-payment/v1/payment/checkout/billing-fields/<payment_processor_id>

Gets billing fields structure by the provided payment processor identifier.

Headers

Name	Value	Required
Authorization*	Bearer <token>

Response

200: OK

{
    "items": [
        {
            "name": "City",
            "placeholder": "City",
            "type": "Text",
            "isRequired": true
        },
        {
            "name": "Country",
            "placeholder": "Country",
            "type": "Select",
            "isRequired": true,
            "isCountryCode": true
        },
        {
            "name": "Region",
            "placeholder": "Region",
            "type": "Text",
            "isRequired": true
        },
        {
            "name": "ZipCode",
            "placeholder": "Zip code",
            "type": "Text",
            "isRequired": true
        }
    ]
}

401: Unauthorized

Unauthorized.

400: Bad Request

{
    "errorMessage": "Payment processor with ID = '12884' not found."
}

Credit Card Payment

POST {API_URL_ISSUED_BY_PAYTIKO}/api/direct-payment/v1/payment/checkout/credit-card

Initiates direct checkout request for the credit card processor type.

Headers

Name	Value	Required
Content-Type*	application/json
Authorization*	Bearer <token>

Body

Name	Type	Description	Required
paymentProcessorId*	Integer	Target payment processor identifiers.
orderId*	String	Order identifier.
firstName*	String	Customer first name.
lastName	String	Customer last name.
country*	String	Customer country code (ISO 3166-1 alpha-2). (2 characters length)
phone	String	Customer phone.
amount*	Numeric	Payment amount.
currency*	String	Payment currency code (ISO 4217). (3 characters length)
notificationUrl*	Absolute URI	Merchant site notification URI.
successPageUrl*	Absolute URI	Merchant site success page URI.
failedPageUrl*	Absolute URI	Merchant site failed page URI.
billingFields*	object	Json map of billing fields.
cardNumber*	String	Full card number.
cardHolder*	String	Card holder name.
cvv*	String	Security code. (3 or 4 digits)
expiryMonth*	Numeric	Card expiry month.
expiryYear*	Numeric	Card expiry year.

Request Body Sample

{
  "paymentProcessorId": 70727,
  "orderId": "ORD001",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[e-mail]",
  "country": "US",
  "phone": "[phone]",
  "amount": 150.75,
  "currency": "USD",
  "notificationUrl": "https://example.com/notify",
  "successPageUrl": "https://example.com/success",
  "failedPageUrl": "https://example.com/fail",
  "billingFields": {
    "City": "Metropolis",
    "Country": "UA",
    "Region": "Northeast",
    "State": "State",
    "Street": "1234 Elm Street",
    "ZipCode": "10001"
  },
  "cardNumber": "5200179966237744",
  "cardHolder": "John Doe",
  "cvv": "123",
  "expiryMonth": 12,
  "expiryYear": 2025
}

Responses

200: OK

{
    "checkoutUrl": "https://direct-checkout.domain.com/?sessionToken=dp-d493053c-302a-4a72-a5cd-0c7cd14d0cff"
}

401: Unauthorized

Unauthorized.

400: Bad Request

{
    "errors": {
        "currency": [
            "'currency' must not be empty."
        ]
    },
    "title": "One or more validation errors occurred.",
}

Alternative Payment

POST {API_URL_ISSUED_BY_PAYTIKO}/api/direct-payment/v1/payment/checkout/alternative-payment

Initiates direct checkout request for the alternatice payment method processor type.

Headers

Name	Value	Required
Content-Type*	application/json
Authorization*	Bearer <token>

Body

Name	Type	Description	Required
paymentProcessorId*	Numeric	Target payment processor identifiers.
orderId*	String	Order identifier.
firstName*	String	Customer first name.
lastName	String	Customer last name.
country*	String	Customer country code (ISO 3166-1 alpha-2). (2 characters length)
phone	String	Customer phone.
amount*	Numeric	Payment amount.
currency*	String	Payment currency code (ISO 4217). (3 characters length)
notificationUrl*	Absolute URI	Merchant site notification URI.
successPageUrl*	Absolute URI	Merchant site success page URI.
failedPageUrl*	Absolute URI	Merchant site failed page URI.
billingFields*	object	Json map of billing fields.

Request Body Sample

{
  "paymentProcessorId": 70694,
  "orderId": "ORD001",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[e-mail]",
  "country": "US",
  "phone": "[phone]",
  "amount": 150.75,
  "currency": "USD",
  "notificationUrl": "https://example.com/notify",
  "successPageUrl": "https://example.com/success",
  "failedPageUrl": "https://example.com/fail",
  "billingFields": {
    "city": "Metropolis",
    "country": "UA",
    "region": "Northeast",
    "state": "State",
    "street": "1234 Elm Street",
    "zipCode": "10001",
    "accountNumber": "11111111111111111",
    "bankAccountType": "1231231231231",
    "routingNumber": 12345678,
    "address": "Address"
  }
}

Responses

200: OK

{
    "checkoutUrl": "https://direct-checkout.paytiko.com/?sessionToken=dp-d493053c-302a-4a72-a5cd-0c7cd14d0cff"
}

401: Unauthorized

Unauthorized.

400: Bad Request

{
    "errors": {
        "currency": [
            "'currency' must not be empty."
        ]
    },
    "title": "One or more validation errors occurred.",
}

JS Events

If you are going to host checkout page in the iframe instead of client redirection, please connect the following JS script to ensure payment flow redirections are properly handled:

https://core.paytiko.com/cdn/js/helpers/js-events-subscribtion.1.0.min.js

How to connect the script on your iframe container page:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Checkout page iframe container</title>
    <!-- Link to Paytiko event subscription helper script -->
    <script src="https://core.paytiko.com/cdn/js/helpers/js-events-subscribtion.1.0.min.js"></script>
</head>
<body>
    <!-- Your HTML content here -->
</body>
</html>