Отримання інформації про платежі

Після того, як платежі було проведено, ви можете отримати інформацію про них з таким рівнем конкретизації:

• Інформація про конкретну транзакцію в межах одного замовленням.
• Інформації про всі транзакції конкретного замовлення.
• Інформація про всі транзакції, що мали місце за певний період часу.
• Реєстр транзакцій у JSON-форматі.

Інформація щодо транзакції

Для отримання інформації про конкретну транзакцію в межах одного замовлення необхідно сформувати запит з HTTP-методом GET та таким набором параметрів:

Parameter	Type	Required	Description
POS_ID	UUID	✅	Merchant's identifier (POS_ID)
ORDER_ID	String	✅	Merchant's order identifier
OPERATION	String	✅	Payment method, e.g. purchase, void, etc.

Приклад запиту на отримання інформації про транзакцію:

$ curl "https://cpay.tranzzo.com/api/v1/pos/${POS_ID}/orders/${ORDER_ID}/${OPERATION}" \
    -H "X-API-AUTH: CPAY-HMAC-SHA256 ${API_KEY}:${SIGNATURE}"

Важливо

Якщо виконується запит на отримання інформації за транзакцією з методом Auth, після якої виконувалось збільшення суми через додаткове резервування (Incremental Auth), у відповіді прийдуть додатковий параметр total_auth_amount, що містить інформацію про загальну суму резервувань в рамках цього замовлення.

total_auth_amount міститиме:

Parameter	Type	Required	Description
original_amount	Number	✅	Total amount (Auth amount plus all Incremental Auths amounts) without fees applied
processed_amount	Number		Total processed by PS amount (Auth amount plus all Incremental Auths amounts) with fees applied

Інформація щодо замовлення або підписки на регулярні платежі

Якщо потрібно отримати інформацію про всі транзакції в межах певного замовлення (ORDER_ID) необхідно сформувати запит з HTTP-методом GET та таким набором параметрів:

Parameter	Type	Required	Description
POS_ID	String	✅	Merchant's identifier (POS_ID)
ORDER_ID	String	✅	Merchant's order identifier

Приклад запиту на отримання інформації про всі транзакції замовлення:

$ curl "https://cpay.tranzzo.com/api/v1/pos/${POS_ID}/orders/${ORDER_ID}" \
    -H "X-API-AUTH: CPAY-HMAC-SHA256 ${API_KEY}:${SIGNATURE}"

Відповідь на такий запит буде містити масив транзакцій, що пов’язані з відповідним замовленням.

Приклад відповіді за двостадійними платежами:

[
  {
    "payment_id":          "c4939398-1dad-4b92-1c34-7f6802379180",
    "order_id":            "111999991",
    "gateway_order_id":    "6320ac9a-aaaa-4912-adb3-5bca2dd560fe",
    "billing_order_id":    "123",
    "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
    "pos_id":              "6eb070d5-7fbe-1176-9488-c152b60dd346",
    "mode":                "direct",
    "method":              "auth",
    "amount":              0.28,
    "currency":            "UAH",
    "payway":              "privat24",
    "eci":                 "7",
    "status":              "success",
    "status_code":         "1000",
    "status_description":  "Transaction is successful.",
    "cc_mask":             "424242******4242",
    "cc_token":            "N2U0ZWExZjU5ZDEzNDqkZjg2YjBaOGYdN2VgZWFcOTYaT2FBaFBUekt6R3hzeDBPU2hO",
    "cc_token_expiration": "2020-10-10T10:10:22",
    "customer_id":         "123",
    "customer_phone":      "+380999999999",
    "created_at":          "2018-10-10T10:10:10.100",
    "processing_time":     "2018-10-10T10:10:22.100",
    "payload":             "",
    "bank_short_name":     "Bank name"
  },
  {
    "operation_id":          "edf7605c-99a8-43be-a1a5-2e96ebac8512",
    "payment_id":          "c4939398-1dad-4b92-1c34-7f6802379180",
    "order_id":              "123",
    "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
    "pos_id":                "6eb070d5-7fbe-1176-9488-c152b60dd346",
    "mode":                  "direct",
    "method":                "capture",
    "amount":                100,
    "currency":              "UAH",
    "status":                "success",
    "status_code":         "1000",
    "status_description":  "Transaction is successful.",
    "created_at":          "2018-10-10T10:11:11.100",
    "processing_time":     "2018-10-10T10:11:12.000"
  }
]

Приклад відповіді за регулярними платежами:

{
  "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":               "purchase",
  "amount":               1,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "success",
  "status_code":          "1000",
  "status_description":   "Transaction is successful",
  "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",
  "recurring": {
     "id": "r7dAMIRmS~3nCiHVFpSC8",
     "status": "init"
  },
  "result_url":           "https://example.com/result",
  "created_at":           "2023-09-14T14:08:13.509",
  "processed_at":         "2023-09-14T14:08:16.112",
  "payload":              "sale=true",
  "bank_short_name":      "Bank name"
}

Аналогічно можна отримати інформацію про транзакції за підпискою на регулярні платежі. Для цього треба відправити GET-запит до ендпоїнту /api/v1/pos/:posId/recurring/:recurringId, де recurringId - унікальний ID підписки.

До запиту також можуть входити такі query-параметри:

Parameter	Required	Description
method	✅	Payment methods (only purchase or refund value is accepted)
status	✅	Transaction status

Інформація про транзакції за певний період

Для отримання інформації про всі транзакції, що було проведено за певний період часу, необхідно сформувати запит з HTTP-методом GET та таким набором параметрів:

Path-параметри:

Parameter	Type	Required	Description
POS_ID	UUID	✅	Merchant's identifier (POS_ID)

Query-параметри:

Parameter	Type	Required	Description
startDate	Number	✅	Time from - UNIX timestamp
enddate	Number	✅	Time to - UNIX timestamp

Приклад запиту:

$ curl "https://cpay.tranzzo.com/api/v1/pos/${POS_ID}/transactions?startDate=${startDate}&enddate=${enddate}" \
    -H "X-API-AUTH: CPAY-HMAC-SHA256 ${API_KEY}:${SIGNATURE}"

Дата у запиті має бути у форматі Unix time. Наприклад:

/api/v1/pos/${POS_ID}/transactions?startDate=1670120382000&enddate=1683721382000

Відповідь на такий запит буде містити масив транзакцій за вказаний період.

Приклад відповіді:

{"projectId":"2a810802-d3ac-4aad-b4c7-74c54cba628e","orderId":"630428489","paymentId":"84f32e8c-6919-49c5-8353-25f6f7c4f371","amount":"1.00","currency":"UAH","method":"purchase","status":"pending","dateTime":"","authCode":"","rrnCode":"","description":"test description","payload":"","customerFee":"0.00","merchantFee":"1.07","paymentSystem":"","recipientCardMask":""}
{"projectId":"2a810802-d3ac-4aad-b4c7-74c54cba628e","orderId":"288558688","paymentId":"620694b9-8e49-42b7-b3cb-950b80529861","amount":"1.00","currency":"UAH","method":"purchase","status":"failure","dateTime":1683646963767,"authCode":"","rrnCode":"","description":"test description","payload":"","customerFee":"0.00","merchantFee":"1.07","paymentSystem":"VISA","recipientCardMask":""}
{"projectId":"2a810802-d3ac-4aad-b4c7-74c54cba628e","orderId":"1369031473","paymentId":"5ee8fb17-f0ec-4e2f-823f-8ffa205f0d7b","amount":"1.00","currency":"UAH","method":"purchase","status":"success","dateTime":1683646725585,"authCode":"","rrnCode":"4428573","description":"test description","payload":"","customerFee":"0.00","merchantFee":"1.07","paymentSystem":"DISCOVER","recipientCardMask":""}

Реєстр транзакцій у JSON-форматі

За необхідності можна отримати реєстр JSON форматі з транзакціями, відфільтрованиим за часом, статусом та методом. Реєстр міститиме вказані у запиті деталі кожного платежу.

Для формування реєстру транзакцій необхідно сформувати запит з HTTP-методом POST та таким набором параметрів:

Parameter	Required	Description
project_id	✅	Merchant's identifier (POS_ID)
start_date	✅	The start date of the period for which the data is required
end_date	✅	Period end date. The maximum period is 31 days
statuses		Array of Transaction status
methods		Payment methods (auth, purchase, capture, void, p2p, credit, lookup, refund, dispute, recurrent)
transaction_details		Array field with the parameters that are received for each of the transactions in report

Окрім того, для такого реєстру можна задати конкретний набір параметрів деталей платежу, які ви бажаєте отримати:

Parameter	Default	Description
orderId	✅	Merchant's order identifier to be captured
paymentId	✅	Tranzzo payment identifier of primary operation
amount	✅	Transaction amount with fees applied
currency	✅	Transaction currency
method	✅	Payment methods
status	✅	Transaction status
dateTime	✅	Transaction date
cardMask	✅	Сard mask
payway	✅	Payway name
customerFee	✅	Customer fee
merchantFee	✅	Merchant fee
entityName		Entity name
projectName		Project name
originalAmount		Transaction amount with no fees applied
exchangeAmount		Exchange amount
exchangeCurrency		Exchange currency
exchangeRate		Exchange rate
tokenizationKind		Tokenization kind
authCode		Transaction authentication code
rrnCode		RRN code
description		Transaction description
payload		Field for custom data
paymentSystem		Payment system
recipientCardMask		Recipient's card mask
reserveAmount		Rolling reserve amount
receiverName		Name of sub merchant in split transaction
receiverAmount		Amount paid to sub merchant in split transaction
receiverFee		Fee amount paid by sub merchant in split transaction

інформація

Зверніть увагу, якщо ви не включите до запиту перелік параметрів, інформація за якими має бути в реєстрі транзакцій, то реєстр буде сформовано з тими параметрами, що відмічені за замовчуванням.

Отримання реєстру транзакцій відбувається у два етапи:

1. Запит на отримання ідентифікатору згенерованого реєстру.
2. Запит на отримання самого реєстру у форматі JSON з використанням попередньо отриманого ідентифікатора.

Приклад запиту на формування реєстру транзакцій:

$ curl --location --request POST 'https://api.tranzzo.com/streaming-report/start' \
--header 'X-API-AUTH: CPAY-HMAC-SHA256 ${API_KEY}:${SIGNATURE}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "project_id": "064ec3f8-8abb-414b-9eb3-49d977213967",
    "start_date": "2022-09-01T12:00:03.007+00:00",
    "end_date": "2022-09-30T23:58:03.007+00:00",
    "statuses": [ "success", "pending", "failure", "init" ],
    "methods": [
        "purchase",
        "auth",
        "capture",
        "void",
        "p2p",
        "credit",
        "lookup",
        "refund",
        "dispute"
        ],
    "transaction_details": [
       "projectId",
       "orderId",
       "paymentId",
       "amount",
       "currency",
       "method",
       "status",
       "dateTime",
       "cardMask",
       "payway",
       "entityName",
       "projectName",
       "originalAmount",
       "exchangeAmount",
       "exchangeCurrency",
       "exchangeRate",
       "tokenizationKind",
       "authCode",
       "rrnCode",
       "description",
       "payload",
       "customerFee",
       "merchantFee",
       "paymentSystem",
       "recipientCardMask"
    ]
}'

Параметри відповіді:

Parameter	Description
report_id	JSON file identifier
count	number of records (transactions)

Приклад відповіді:

{"report_id":"57e79df2-b374-4998-9b0e-ac7848760bed","count":384}

Приклад відповіді у випадку, коли реєстр ще не сформовано:

{
  "message": "Report not ready",
  "code": "report_not_ready"
}

Для отримання сформованого реєстру транзакцій у JSON-форматі необхідно відправити запит з HTTP-методом GET з отриманим ідентифікатором реєстру report_id.

Приклад запиту:

$ curl --location --request GET 'https://api.tranzzo.com/streaming-report/fetch/57e79df2-b374-4998-9b0e-ac7848760bed'
--header 'X-API-AUTH: CPAY-HMAC-SHA256 ${API_KEY}:${SIGNATURE}'

Відповідь на запит буде містити JSON з кількістю записів, що дорівнює отриманому у параметрі count значенню. Кожен запис містить набір параметрів, вказаних при формуванні реєстру транзакцій, або параметрів за замовчуванням.

Приклад відповіді:

{"projectId":"064ec3f8-8abb-414b-9eb1-49d977213999","orderId":"1456649508235","paymentId":"b2dc0fb9-2de4-4a30-9447-088ce415fb58","amount":"3","currency":"UAH","method":"void","status":"success","dateTime":1662033684016,"cardMask":"414141******2284","payway":"applepay","entityName":"","projectName":"Project","originalAmount":"3","exchangeAmount":"0.00","exchangeCurrency":"","exchangeRate":"0.00","tokenizationKind":"","authCode":"238530","rrnCode":"003561423521","description":"description","payload":"","customerFee":"0.00","merchantFee":"0.00","paymentSystem":"MASTERCARD","recipientCardMask":""}
{"projectId":"064ec3f8-8abb-414b-9eb1-49d977213988","orderId":"1456649508236","paymentId":"b2dc0fb9-2de4-4a30-9447-088ce415fb51","amount":"2","currency":"UAH","method":"auth","status":"success","dateTime":1662033684916,"cardMask":"537541******2284","payway":"gpay","entityName":"","projectName":"Project","originalAmount":"2","exchangeAmount":"0.00","exchangeCurrency":"","exchangeRate":"0.00","tokenizationKind":"","authCode":"238530","rrnCode":"003561423521","description":"description","payload":"","customerFee":"0.00","merchantFee":"0.00","paymentSystem":"MASTERCARD","recipientCardMask":""}
{"projectId":"064ec3f8-8abb-414b-9eb2-49d977213967","orderId":"1456649508238","paymentId":"b2dc0fb9-2de4-4a30-9447-088ce415fb50","amount":"1","currency":"UAH","method":"purchase","status":"success","dateTime":1662033680916,"cardMask":"537541******1184","payway":"cc","entityName":"","projectName":"Test Project","originalAmount":"1","exchangeAmount":"0.00","exchangeCurrency":"","exchangeRate":"0.00","tokenizationKind":"","authCode":"238530","rrnCode":"003561423521","description":"test qa","payload":"","customerFee":"0.00","merchantFee":"0.00","paymentSystem":"MASTERCARD","recipientCardMask":""}