Integration Guideline

1. Prerequisites

Before you begin integration, ensure the following:

You have an active merchant account with paytech.
You have access to your API keys and the Signing Key for webhook verification.
All requests must:
- Use HTTPS (base URL: https://engine.pay.tech for production, https://engine-sandbox.pay.tech for sandbox environment)
- Be made using HTTP POST, GET, or PATCH methods as specified
- Include a Bearer Token in the request header (it corresponds to your Shop API Key)
- Use JSON as the request body format for POST and PATCH methods

2. Main API Endpoints

Endpoint	Method	Purpose
/api/v1/payments	POST	Create a payment (DEPOSIT, WITHDRAWAL, REFUND)
/api/v1/payments	GET	Retrieve a list of payments
/api/v1/payments/{id}	GET	Retrieve payment details by ID
/api/v1/payments/{id}	PATCH	Used in Host-to-Host (H2H) flow for updates
/api/v1/balances	GET	Retrieve available balances for withdrawal

3. Integration Options

🔁 Redirect (Checkout) Flow

Create Payment via POST /api/v1/payments
Receive response with redirectUrl
Redirect the customer to redirectUrl for completing the payment

✅ Simple implementation, UI hosted by the gateway

🔄 Host-to-Host (H2H) Flow

‼️ Available only for specific payment methods – contact support before the integration ‼️

Create Payment via POST /api/v1/payments
Ignore redirectUrl, extract id
Make a PATCH /api/v1/payments/{id} with the customer’s IP:
```
{
  "customerIp": "81.4.178.167"
}
```
Use the externalRefs object to communicate further payment instructions to the customer

✅ Full control over the checkout flow

4. Getting Final Payment Status

‼️ Caution: for some payment methods the final transaction amount may be different from the initial requested amount. ‼️

4.1. Webhook Handling

Webhooks notify you when a payment reaches a final state: COMPLETED, DECLINED, CANCELLED, AUTHORIZED
Configure your webhook URL either:
In shop settings, or
Inline using the webhookUrl parameter in the POST /api/v1/payments request (overrides settings).

Webhook Verification

Set a Signing Key in the shop settings.
Webhook requests include a Signature header with an HMAC-SHA256 hash of the JSON body using the Signing Key.

Example Payload (DEPOSIT - CANCELLED)

{
  "id": "9e9003d7f3324fc6828481c665d8bab5",
  "paymentType": "DEPOSIT",
  "state": "CANCELLED",
  "paymentMethod": "BANKTRANSFER",
  "amount": 2000,
  "currency": "CLP",
  "errorCode": "1.04",
  "errorMessage": "Cancelled by Timeout"
}

4.2. Checking State by Payment ID

You can request payment status by sending the request GET /api/v1/payments/{id}

Example Response (DEPOSIT - DECLINED)

{
  "timestamp": "2020-10-07T13:36:32.595+00:00",
  "status": 200,
  "result": {
    "id": "91d27876e87f4b22b3ecd53924bf973d",
    "referenceId": "payment-123",
    "created": "2030-12-25T10:11:12",
    "paymentType": "DEPOSIT",
    "state": "DECLINED",
    "description": "Deposit via TEST shop",
    "paymentMethod": "BASIC_CARD",
    "paymentMethodDetails": {
      "customerAccountNumber": "400000***0002",
      "cardToken": "3529d42227424875af8722cbf54d7073",
      "cardholderName": "John Doe",
      "cardExpiryMonth": "01",
      "cardExpiryYear": "2030",
      "cardBrand": "VISA",
      "cardIssuingCountryCode": "CY"
    },
    "amount": 11.12,
    "currency": "EUR",
    "customerAmount": 15,
    "customerCurrency": "USD",
    "errorCode": "4.01",
    "errorMessage": "Insufficient Funds",
    "externalResultCode": "03",
    "customer": {
      "referenceId": "customer_123",
      "citizenshipCountryCode": "AU",
      "firstName": "John",
      "lastName": "Smith",
      "dateOfBirth": "2001-12-03",
      "email": "[email protected]",
      "phone": "357 123123123",
      "locale": "ru"
    },
    "billingAddress": {
      "addressLine1": "7, Sunny street",
      "addressLine2": "Office 3",
      "city": "Limassol",
      "countryCode": "CY",
      "postalCode": "4141",
      "state": "CA"
    }
  }
}