Gateway API Integration Guideline

1. Prerequisites

Before you begin integration, ensure the following:

• You have an active merchant account with paytech.
• You have access to the Shop API Key to call API endpoints and the Shop Signing Key for webhook verification. The keys for the sandbox and production environments are different.
• 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 the Shop API Key in the Authorization header as a Bearer token
  • Use JSON as the request body format for POST and PATCH methods

2. Main API Endpoints

3. Integration Options

🔁 Standard flow

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

When using the basic_card payment method, the same process applies to both StS integration mode (card data is collected on the merchant side) and hosted page integration mode (card data is collected on the payment gateway checkout page). There is also no difference in the process for 3DS and non-3DS payments.

🔄 Option to skip redirection to checkout page

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

1. Create Payment via POST /api/v1/payments
2. Ignore redirectUrl, extract id
3. Make a PATCH /api/v1/payments/{id} with the customer’s IP:

   {
     "customerIp": "81.4.178.167"
   }
   

4. Use the externalRefs object to pass further payment instructions to the customer

This method can be used in cases where interaction with the customer (for example, a redirect to an external address or a request for additional information) is not required.

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"
    }
  }
}