Transactions and Settlements
Every payment, payout, transfer, refund, and settlement in the Credova system is associated with a transaction. Credova leverages double entry accounting to track debit credits. This helps with end of day reconciliation processes.
This guide shows how to search transactions and view the details of one. Transactions appear after you create payments, payouts or refunds, for example with Accept Card Payments. You can also view the settlements that group a day's transactions.
Before you start
Secret Key- Authenticates requests from your server. Never send it to the browser.
Retrieve a Transaction
We will need to reference the payment's transaction_id to pull information about the payment.
For example, given you have a payment:
{
"id": "pmt_2YKewBonG4tgk12MheY3PiHDy",
"account_id": "acc_B518niGwGYKzig6vtrRVZGGGV",
"environment": "test",
"status": "succeeded",
"transaction_id": "trx_95rvMJvAVeG68W4NtLdfkN3LG",
...
}
Get Transaction by ID
We need to make a call to Get Transaction endpoint:
curl 'https://api.publicsquare.com/transactions/trx_95rvMJvAVeG68W4NtLdfkN3LG?include_type=true' \
-H 'Accept: application/json' \
-H 'X-API-KEY: <SECRET_API_KEY>'
Transaction Response
Given the above examples, you should see a transaction response similar to:
{
"id": "trx_95rvMJvAVeG68W4NtLdfkN3LG",
"account_id": "acc_B518niGwGYKzig6vtrRVZGGGV",
"environment": "test",
"status": "succeeded",
"amount": 1000,
"fee_amount": 36,
"net_amount": 964,
"currency": "USD",
"type_id": "pmt_2YKewBonG4tgk12MheY3PiHDy",
"type": "payment",
"processor": "nuvei",
"processor_id": "7110000000010554769",
"payment": {
"id": "pmt_2YKewBonG4tgk12MheY3PiHDy",
"account_id": "acc_B518niGwGYKzig6vtrRVZGGGV",
"environment": "test",
"status": "succeeded",
"transaction_id": "trx_95rvMJvAVeG68W4NtLdfkN3LG",
"amount": 1000,
"amount_capturable": 0,
"amount_charged": 1000,
"amount_refunded": 0,
"refunded": false,
"currency": "USD",
"payment_method": {
"card": {
"id": "card_AjkCFKAYiTsjghXWMzoXFPMxj",
"cardholder_name": "John Smith",
"last4": "4242",
"exp_month": "12",
"exp_year": "2025",
"brand": "visa",
"avs_code": "Y",
"cvv2_reply": "M",
"fingerprint": "CC2XvyoohnqecEq4r3FtXv6MdCx4TbaW1UUTdCCN5MNL"
}
},
"customer": {
"id": "cus_7Ay5mcUXAxwrN6wQEQUVEHBCJ",
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@email.com",
},
"billing_details": {
"address_line_1": "111 Test St.",
"city": "Des Moines",
"state": "IA",
"postal_code": "51111",
"country": "US"
},
"shipping_address": {
"address_line_1": "111 Colorado Ave.",
"address_line_2": "Apt 403",
"city": "Des Moines",
"state": "IA",
"postal_code": "51111",
"country": "US"
},
"created_at": "2024-06-30T01:02:29.212Z",
"modified_at": "2024-06-30T01:02:29.212Z"
},
"created_at": "2024-06-30T01:02:29.212Z",
"modified_at": "2024-06-30T01:02:29.212Z"
}
Search Transactions
In many cases, you may need to search transactions to find records associated with a specific customer, payment method, or an order ID from your system. Credova offers the ability to search and export across most fields of a customer, payment method, and transaction.
To perform a search, we can do the following:
curl 'https://api.publicsquare.com/transactions?query=order1234' \
-H 'Accept: application/json' \
-H 'X-API-KEY: <SECRET_API_KEY>'
This should return a paginated result:
{
"pagination": {
"total_items": 924,
"page_number": 1,
"page_size": 10,
"total_pages": 93
},
"data": [
{
"id": "trx_95rvMJvAVeG68W4NtLdfkN3LG",
"account_id": "acc_B518niGwGYKzig6vtrRVZGGGV",
"environment": "test",
"status": "succeeded",
"external_id": "order1234",
"amount": 1000,
"fee_amount": 36,
"net_amount": 964,
"currency": "USD",
"type_id": "pmt_2YKewBonG4tgk12MheY3PiHDy",
"type": "payment",
"processor": "nuvei",
"processor_id": "7110000000010554769",
"created_at": "2024-06-30T01:02:29.212Z",
"modified_at": "2024-06-30T01:02:29.212Z"
},
...
]
}
Searchable Fields
The following fields are searchable using the query parameter:
| Entity | Field |
|---|---|
payment | id |
payment | fraud_decision |
refund | id |
refund | amount |
payout | id |
transaction | id |
transaction | type |
transaction | status |
transaction | external_id |
transaction | processor |
transaction | processor_id |
transaction | amount |
transaction | net_amount |
transaction | settlement_id |
customer | id |
customer | external_id |
customer | first_name |
customer | last_name |
customer | business_name |
customer | email |
customer | phone |
customer | government_identifier_last4 |
card | cardholder_name |
card | last4 |
bank_account | account_holder_name |
bank_account | account_number_last4 |
To search over more fields, contact support.
Retrieve a Settlement
At the end of every business day, all payments, payouts, and refunds are settled. During this process, funds are either deposited or withdrawn from your business bank account based upon the sum of that days transactions. This process generates a Settlement record in the Credova system which summarizes that days transactions and creates an association with the transactions in that days' batch.
We will assume we have a settlement with ID stl_BGDLZjBLAgNbyqCzJxchSoh5k to pull information about the settlement.
We need to make a call to Get Settlement endpoint:
curl 'https://api.publicsquare.com/settlements/stl_BGDLZjBLAgNbyqCzJxchSoh5k' \
-H 'Accept: application/json' \
-H 'X-API-KEY: <SECRET_API_KEY>'
Settlement Response
Given the above examples, you should see a settlement response similar to:
{
"id": "stl_BGDLZjBLAgNbyqCzJxchSoh5k",
"account_id": "acc_B518niGwGYKzig6vtrRVZGGGV",
"environment": "test",
"transaction_id": "trx_95rvMJvAVeG68W4NtLdfkN3LG",
"payment_amount": 1500,
"payment_count": 3,
"refund_amount": 500,
"refund_count": 1,
"total_count": 4,
"amount": 1000,
"currency": "USD",
"settled_at": "2024-06-30T00:00:00.000Z",
"transaction": {
"id": "trx_95rvMJvAVeG68W4NtLdfkN3LG",
"account_id": "acc_B518niGwGYKzig6vtrRVZGGGV",
"environment": "production",
"external_id": "e797ef3c-b586-4333-af90-7168d8427d85",
"status": "succeeded",
"amount": -1000,
"fee_amount": 0,
"net_amount": -1000,
"currency": "USD",
"type_id": "pmt_2YKewBonG4tgk12MheY3PiHDy",
"type": "payment",
"processor": "nuvei",
"processor_id": "7110000000010554769",
"created_at": "2024-06-30T01:02:29.212Z",
"modified_at": "2024-06-30T01:02:29.212Z"
},
"created_at": "2024-06-30T01:02:29.212Z",
"modified_at": "2024-06-30T01:02:29.212Z"
}
Get Transactions for a Settlement
You may also want to view all associated transactions for a settlement. We can leverage the Get Transactions for a Settlement endpoint:
curl 'https://api.publicsquare.com/settlements/stl_BGDLZjBLAgNbyqCzJxchSoh5k/transactions' \
-H 'Accept: application/json' \
-H 'X-API-KEY: <SECRET_API_KEY>'
Settlement's Transactions Response
This should return a paginated result of transactions for the settlement:
{
"pagination": {
"total_items": 924,
"page_number": 1,
"page_size": 10,
"total_pages": 93
},
"data": [
{
"id": "trx_95rvMJvAVeG68W4NtLdfkN3LG",
"account_id": "acc_B518niGwGYKzig6vtrRVZGGGV",
"environment": "test",
"status": "succeeded",
"amount": 1000,
"fee_amount": 36,
"net_amount": 964,
"currency": "USD",
"type_id": "pmt_2YKewBonG4tgk12MheY3PiHDy",
"type": "payment",
"settlement_id": "stl_BGDLZjBLAgNbyqCzJxchSoh5k",
"processor": "nuvei",
"processor_id": "7110000000010554769",
"created_at": "2024-06-30T01:02:29.212Z",
"modified_at": "2024-06-30T01:02:29.212Z"
},
...
]
}
Conclusion
This guide showed you how to retrieve and search transactions, retrieve a settlement, and view the transactions for a settlement. Every payment, refund, payout, and settlement in the system generates a transaction. This guide can be useful for end of day reconciliation processing.