API integration

This type of integration can be used to perform a Void transaction.

Interaction format:

An image from the static

Peculiarities of using this integration to perform void for the pre-authorization operation:

A request to the Tranzzo API for void operation can be applied only to primary pre-authorization transactions (auth) with the successful status (success).
Use the HTTP POST method.

To initiate a void operation, a request to the Tranzzo API must contain the following parameters:

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`order_id`	String	✅	Merchant's order identifier to be captured (max length is 32 characters)
`order_currency`	CURRENCY	✅	Currency of original order
`comment`	String		Void comment. Can be used for describing reasons of void or for passing another data about operation (max length is 2048 characters)
`server_url`	URL		Webhook notification will be sent to this URL

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/void" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY-HMAC-SHA1 ${API_KEY}:${SIGNATURE}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "UAH",
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/"
    }'

Response parameters:

Parameter	Type	Description
`operation_id`	UUID	Unique Tranzzo void identifier
`payment_id`	UUID	Tranzzo payment identifier of primary operation
`order_id`	String	Merchant's `order_id` of primary operation (max length is 32 characters)
`transaction_id`	UUID	Unique Tranzzo transaction identifier
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	MODE	`direct`
`method`	METHOD	`void`
`amount`	Number	Actual void amount
`currency`	CURRENCY	Transaction currency
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	Tranzzo payment status code
`status_description`	STATUS_DESCRIPTION	Tranzzo payment status code description
`created_at`	TIMESTAMP	Timestamp when transaction was created
`processed_at`	TIMESTAMP	Timestamp when transaction was updated last time
`fee`	Object	Amount and currency of commission
`comment`	String	Void comment

Response example:

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "void",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1009",
  "status_description":  "Reverse successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":     "2018-10-10T10:10:12.000",
  "fee":                 null,
  "comment":             "10101"
}

To test the void payment process:

Perform the initial backup operation using the authentication data of the test project.
Initiate a secondary operation of Void for the primary pre-authorization operation.
Configure webhooks.
Use the test data to obtain different operation result codes.
Handle received errors.

After completing the testing to go live, you need to make changes to the authentication data, using the data of the previously created live project.

See also:​

See also: