Getting transaction information

Once payments have been processed, you can obtain information about them at the following levels of detail:

• Information about a specific transaction within a single order.
• Information about all transactions of a specific order.
• Information about all transactions that took place over a specific period of time.
• A transaction register in JSON format.

Details about a specific transaction

To obtain information about a specific transaction within an order, send a request using the GET HTTP method with the following set of parameters:

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.

Example of a request to obtain information about a transaction:

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

Order and subscription information

To obtain information about all transactions within a specific order (ORDER_ID), send a request using the GET HTTP method with the following set of parameters:

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

Example of a request to obtain information about all transactions of an order:

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

The response to this request will contain an array of transactions linked to the corresponding order.

Example response for two-step payments:

[
  {
    "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":            "EUR",
    "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":      "+480999999999",
    "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":              "EUR",
    "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"
  }
]

Example response for recurring payments:

{
  "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":             "EUR",
  "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":       "tom.hanks@example.com",
  "customer_phone":       "+480999999999",
  "customer_country":     "PL",
  "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"
}

You can obtain information about transactions of a recurring payment subscription in a similar way. To do this, send a GET request to the /api/v1/pos/:posId/recurring/:recurringId endpoint, where recurringId is the unique ID of the subscription.

The request can also include the following query parameters:

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

Information on all transactions over a specific period

To obtain information about all transactions carried out over a specific period of time, send a request using the GET HTTP method with the following set of parameters:

Path parameters:

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

Query parameters:

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

Request example:

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

The date in the request must be in Unix time format. For example:

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

The response to this request will contain an array of transactions for the specified period.

Response example:

{"projectId":"2a810802-d3ac-4aad-b4c7-74c54cba628e","orderId":"630428489","paymentId":"84f32e8c-6919-49c5-8353-25f6f7c4f371","amount":"1.00","currency":"EUR","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":"EUR","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":"EUR","method":"purchase","status":"success","dateTime":1683646725585,"authCode":"","rrnCode":"4428573","description":"test description","payload":"","customerFee":"0.00","merchantFee":"1.07","paymentSystem":"DISCOVER","recipientCardMask":""}

Transaction register in JSON format

You can also obtain a transaction register in JSON format, filtered by time, status, and method. The register will contain the details of each payment specified in the request.

To generate a transaction register, send a request using the POST HTTP method with the following set of parameters:

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 statuses
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

You can also specify a particular set of payment detail parameters that you want to include in the register:

Parameter	Default	Description
orderId	✅	Merchant's order identifier to be captured
paymentId	✅	Velora payment identifier of primary operation
amount	✅	Transaction amount with fees applied
currency	✅	Transaction currency
method	✅	Payment methods
status	✅	Transaction status
dateTime	✅	Transaction date
cardMask	✅	Card 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

info

Please note, if you do not include a list of parameters that should be in the transaction register in the request, the register will be generated with the default parameters.

Generating a transaction register takes place in two stages:

1. A request to obtain the identifier of the generated register.
2. A request to obtain the register itself in JSON format using the previously obtained identifier.

Example request to generate a transaction register:

$ curl --location --request POST 'https://api.veloragate.com/streaming-report/start' \
--header 'X-API-Auth:CPAY 28e957dc-aff7-4575-bd0f-739ec9bc77ee:UnE2Tmc4N0FnVm1JMmxHcGRIdmJ4aHZq' \
--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"
    ]
}'

Response parameters:

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

Response example:

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

Example response when the register has not yet been generated:

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

To obtain the generated transaction register in JSON format, send a request using the GET HTTP method with the received register identifier report_id.

Request example:

$ curl --location --request GET 'https://api.veloragate.com/streaming-report/fetch/57e79df2-b374-4998-9b0e-ac7848760bed'
--header 'X-API-Auth:CPAY 28e957dc-aff7-4575-bd0f-739ec9bc77ee:UnE2Tmc4N0FnVm1JMmxHcGRIdmJ4aHZq'

The response to the request will contain JSON with a number of records equal to the value received in the count parameter. Each record will contain the set of parameters specified when the transaction register was generated, or the default parameters.

Response example:

{"projectId":"064ec3f8-8abb-414b-9eb1-49d977213999","orderId":"1456649508235","paymentId":"b2dc0fb9-2de4-4a30-9447-088ce415fb58","amount":"3","currency":"EUR","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":"EUR","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":"EUR","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":""}