API integration

Refunds can be made both for the full amount of a split payment and for all or part of the amount of a separate subpayment included in it.

Interaction format:

Refund of the full amount of the split payment (full refund)

Peculiarities of using this integration to refund the full payment amount:

1. A request to the Tranzzo API for a refund can only be applied to (purchase) or (capture) transactions with the successful (success) statuses.
2. Use the HTTP POST method.

Request 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)
currency	CURRENCY	✅	Currency of original order
refund_amount	Number	✅	Amount to be refunded. Must be a positive number. The number of decimal digits must be less than or equal to 2 (e.g., 100.00, 250, 50.50)
comment	String		Refund comment. Can be used for describing reasons of refund or for passing another data about operation (max length is 2048 characters)
server_url	URL		Webhook notification will be sent to this URL
split	Array[SplitPayment]	✅	Split payment properties

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/split/refund" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "currency":       "UAH",
      "refund_amount":  100,
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/capture",
      "split":[
          {
              "amount":          70,
              "sub_merchant_id": "${SUB_MERCHANT_ID_1}"
          },
          {
              "amount":          30,
              "sub_merchant_id": "${SUB_MERCHANT_ID_2}"
          }
      ]
    }'

Response parameters:

Parameter	Type	Description
operation_id	UUID	Unique Tranzzo refund 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	refund
amount	Number	Actual refund 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
processing_time	TIMESTAMP	Timestamp when transaction was updated last time
fee	Object	Amount and currency of commission
comment	String	Refund comment
split_fee	Object	Amount and currency of commission by marketplace and sub-merchants

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":              "refund",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1004",
  "status_description":  "Refund successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processing_time":     "2018-10-10T10:10:12.000",
  "fee":                 null,
  "comment":             "10101"
}

Refund of subpayment

If necessary, the full amount of the subpayment or a separate part of it can be refunded. To carry out such an operation, the request must contain the following additional parameters:

Parameter	Type	Required	Description
amount	Number	✅	Amount to be refunded.Must be a positive number. The number of decimal digits must be less than or equal to 2 (e.g., 100.00, 250, 50.50)
sub_merchant_id	UUID	✅	Unique Sub merchant identifier (to get the identifier, please contact support at [email protected])

caution

When refunding multiple sub-payments, the request must include information for each sub-merchant and the corresponding refund amount

Next steps

To test the refund payment process:

• Carry out a ‘pre-authorization - capture’ payment combination using the authentication data of the test project.
• Initiate a secondary operation of refund for the above transaction.
• 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:

• Adding payment methods