Skip to main content

API integration

Direct integration​

Direct integration will allow you to accept payments using your own payment page.

Interaction format:

An image from the static

info

Note: the use of direct integration when collecting card data on the merchant side requires PCI DSS certification. Alternatively, you can use our tokenization widget by implementing it on your site.

The use of direct integration with two-step payments involves the following peculiarities (in addition to those described for one-step payment):

  • In a request to the Tranzzo API, the method parameter must contain the auth value.

The rest of the parameters are similar to those provided for one-step split payments.

Depending on what is used in the request: full card data or a token, you need to pass the following parameters:

  • Using full card data: cc_number, exp_month, exp_year, card_cvv
  • Using token: cc_token
  • Using VTS / MDES tokens: cc_number, exp_month, exp_year, cryptogram.

Additionally, the decrypted VTS/ MDES payment must also include specific parameters in the cryptogram:

ParameterTypeRequiredDescription
typeString✅Network token type: vts (Visa Token Service) or mdes (Mastercard Digital Enablement Service)
cryptogramString✅Payment cryptogram in Base64 format. Issued by the tokenization network (Visa or Mastercard) and valid within a single transaction.
eciStringElectronic Commerce Indicator. An indicator of the transaction’s authentication level, passed together with the cryptogram.
info

In addition to supporting payments with tokens received after card payments, we also support tokens generated during the first payment via Apple Pay or Google Pay™. These tokens should be passed in the cc_token parameter

For example:

"cc_token":"rcr:ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv" (token after an Apple Pay or Google Pay™ payment)
or
"cc_token": "ODJkZjBhNmY2OTMyND7sSjdD0S8TQzOXU3ZDFhYzI6cWJmWHFmMHlz M3hYaXJMWEZv" (token after a card payment).
info

If a payment is made with a card for which 3D Secure authentication has already been completed by an external service, the request must include the three_d_secure parameter containing the authentication result:

ParameterTypeRequiredDescription
cavvString✅Cardholder Authentication Verification Value. A cryptographic value derived by the cardholder’s bank after successful 3D Secure authentication.
eciString✅Electronic Commerce Indicator. An indicator of the transaction’s authentication level, passed together with the cryptogram.
ds_transaction_idString✅3DS directory service transaction ID. A unique identifier generated by the payment network's Directory Service to track a specific 3D Secure authentication attempt.
statusString✅3D Secure Transaction Status. The final result of the authentication process (for example, Y for successful or A for attempted).
versionString3D Secure Message Version. The specific version of the 3D Secure protocol used for the authentication (for example, 2.1.0 or 2.2.0).

Example request using card data:

$ curl "https://cpay.tranzzo.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY-HMAC-SHA256 ${API_KEY}:${SIGNATURE}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "auth",
      "amount":           1,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "cc_number":        "424242******4242",
      "exp_month":        2,
      "exp_year":         24,
      "cc_cvv":           "***",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "customer_referrer": "https://example.com",
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "uk-UA",
          "browserTimeZone":         "Europe/Kiev",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      }
    }'

Example request using token:

$ curl "https://cpay.tranzzo.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY-HMAC-SHA256 ${API_KEY}:${SIGNATURE}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "auth",
      "amount":           1,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "cc_token":         "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "customer_referrer": "https://example.com",
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "uk-UA",
          "browserTimeZone":         "Europe/Kiev",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      }
    }'

Example request using decrypted VTS / MDES token:

$ curl "https://cpay.tranzzo.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY-HMAC-SHA256 ${API_KEY}:${SIGNATURE}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id": "${POS_ID}",
      "mode": "direct",
      "method": "purchase",
      "amount": 1,
      "currency": "UAH",
      "description": "Order description",
      "order_id": "123",
      "cc_number": "4242424242424242",
      "exp_month": 2,
      "exp_year": 30,
      "cryptogram": {
        "type": "vts",
        "cryptogram": "AEIokIcx0ESqByEoIN1yAoABFA=",
        "eci": "05"
      },
      "customer_fname": "Olena",
      "customer_lname": "Shevchenko",
      "customer_id": "1234567890",
      "order_3ds_bypass": "never",
      "server_url": "https://callback.blackhole.com/callback"
    }'

Response parameters:

ParameterTypeDescription
payment_idUUIDUnique Tranzzo payment identifier
order_idString(≤256)Unique identifier of order
gateway_order_idGW_IDUnique order identifier in bank acquirer system.
billing_order_idBILLING_IDUnique Tranzzo billing identifier
transaction_idUUIDTranzzo transaction identifier
pos_idUUIDMerchant's identifier (POS_ID`)
modeMODEdirect
methodMETHODPayment method (auth)
amountNumberTransaction amount
currencyCURRENCYTransaction currency (ISO_4217)
descriptionString(≤2048)Payment description
statusSTATUSTransaction status
status_codeSTATUS_CODETranzzo payment status code
status_descriptionSTATUS_DESCRIPTIONTranzzo payment status code description
user_action_requiredBooleanEither customer action is required to proceed with payment
user_action_urlURLIf user_action_required is true then user should be redirected to this URL
eciECIElectronic Commerce Indicator - authentication result of credit card payment on 3D Secure
mccMCCMCC for this transaction
options_3dsString3-D Secure flow option
cc_maskCC_MASKCard number mask
cc_tokenCC_TOKENTranzzo card token generated for this card
cc_token_expirationStringToken expiration timestamp
customer_idStringCustomer’s identifier in merchant's system
customer_ipStringCustomer’s IP address
customer_fnameStringCustomer’s first name
customer_lnameStringCustomer’s last name
customer_patronymStringCustomer’s patronym
customer_emailStringCustomer’s email
customer_phoneStringCustomer’s phone
customer_countryStringCustomer’s country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
customer_birthdayStringCustomer’s birthday (format: yyyy-MM-dd)
result_urlURLCustomer will be redirected to this URL after payment.
created_atTIMESTAMPTimestamp when transaction was created
processed_atTIMESTAMPTimestamp when transaction was updated last time
payloadStringField for custom data
bank_short_nameStringBank short name.
receipt_urlURLURL link to the receipt for the corresponding transaction

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "auth",
  "amount":               1,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "http://secure.secure3d.net/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "[email protected]",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processed_at":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true",
  "bank_short_name":      "Bank name",
  "receipt_url": "https://cpay.tranzzo.com/public/receipt/12491284012940129402424124124124124ffef3re3rf32f2vf"
}

In addition, the following data regarding the fingerprint of the payer's browser must be submitted in the request:

ParameterTypeDescription
browserColorDepthStringBrowser's color depth
browserScreenHeightStringBrowser's screen height
browserScreenWidthStringBrowser's screen width
browserJavaEnabledStringBrowser's java enabled
browserLanguageStringBrowser's language
browserTimeZoneStringBrowser's timezone
browserTimeZoneOffsetStringBrowser's timezone offset
browserAcceptHeaderStringBrowser's accept header
browserIpAddressStringBrowser's IP address
browserUserAgentStringBrowser's user agent

An example of a payer's browser fingerprint:

"browser_fingerprint": {
  "browserColorDepth":       "24",
  "browserScreenHeight":     "860",
  "browserScreenWidth":      "1600",
  "browserJavaEnabled":      "false",
  "browserLanguage":         "uk-UA",
  "browserTimeZone":         "Europe/Kiev",
  "browserTimeZoneOffset":   "-120",
  "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
  "browserIpAddress":        "127.0.0.1",
  "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
}

Hosted integration​

Hosted integration allows you to accept payments from customers using the Tranzzo payment page.

Interaction format:

An image from the static

The use of hosted integration with two-step payments involves the following peculiarities (in addition to those described for one-step payment):

  • In a request to the Tranzzo API, the method parameter must contain the auth value.

The rest of the parameters for pre-authorization (auth) transaction are similar to those provided for one-step split payments.

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY-HMAC-SHA256 ${API_KEY}:${SIGNATURE}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "hosted",
      "method":           "auth",
      "amount":           1,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "customer_referrer": "https://example.com",
    }'

Next steps​

The procedure of testing and going online is similar to that provided for one-step payment.

See also:​