Reconcile transactions

• Direct model
• Embedded model
• Crypto
• Fiat
• Stablecoin

Reconciliation allows you to verify that your internal transaction records match BVNK's transaction data. By comparing your system's records with BVNK's transaction reports, you can identify discrepancies, ensure accounting accuracy, and maintain compliance with financial reporting requirements.

You can generate reconciliation reports manually on demand or automatically on a schedule. Reports are available in CSV or JSON format and can be delivered via email or webhook. Use these reports to:

• Verify transaction amounts and balances.
• Identify missing or duplicate transactions.
• Reconcile fees and currency conversions.
• Prepare accounting records and financial statements.

Prerequisites

To use the Reconciliation API, you need to have:

• BVNK account in the sandbox or production environment
• API credentials: Hawk Auth ID and Secret Key

---

Retrieve transaction history

Create reconciliation reports manually using the API or the Portal.

API

To generate transaction and balance reports via API, use the following endpoints:

• POST /ledger/v1/reports: Recommended for reconciliation. Generates comprehensive transaction reports for specific wallets or all wallets. Supports CSV and JSON formats, as well as webhook or email delivery.
• GET /ledger/v1/transactions: Use for real-time transaction queries. Returns paginated results suitable for API integration, not bulk reconciliation.
• GET /api/wallet/balances: Use to retrieve balance snapshots for a specific date. Useful for balance reconciliation.
• GET /api/v1/pay/summary: Use for crypto payment history only. Limited to crypto transactions.
• GET /api/v2/channel: Use for channel payment history only. Limited to channel transactions.

See the endpoints' documentation for more information.

Portal

1. On the Portal, go to the Transaction history section and click Export Transactions.

   

2. In the Export wallet transactions form, select Once-off to generate a one-time report.

3. Configure the exported report:

   • Report type:

     • Transactions: Generates a report including all transactions in your account.

       

     • Wallet balances: Generates a report of wallet balances as of the selected date. Useful for checking balance snapshots.

       

   • Period:

     • Last 30 days: Includes transactions from the past 30 days counting backward from today.
     • Previous calendar month: Includes all transactions from the previous complete calendar month.
     • Previous 3 calendar months: Includes all transactions from the previous three complete calendar months.
     • Custom: Includes all transactions from a specific start and end date for the report period.
     • Balance date: Generates a wallet balance report for the selected date only. Applies exclusively to the 'Wallet balances' report type.

4. Click Send to email. The CSV file will be sent to your email inbox.

Also, you can generate a report for a specific wallet:

1. Go to the Wallets section and click on the wallet you want to generate a report for.

2. On the Transaction history tab, click Export.

3. Configure the exported report:

   • Report type: Transactions or Wallet Balance.
   • Period: Same as above.
   • Export format:
     • Transaction CSV: Exports transaction data in CSV format for import into accounting systems or spreadsheets.
     • PDF Statement: Generates a formatted PDF statement suitable for record-keeping or sharing.
   

4. Click Send to email. The CSV file will be sent to your email inbox.

Schedule a recurring report

Schedule recurring reports for automated email delivery on a regular basis.

info

You can create only one recurring export per account.

Scheduled reports are generated for the previous time period:

• Daily: Generated for the previous day. For example, a report scheduled for January 2nd contains data from January 1st.
• Weekly: Generated for the previous week. For example, a report scheduled for Wednesday contains data from the previous Tuesday to the current Wednesday.
• Monthly: Generated for the previous month. For example, a report scheduled for February 1st contains data from January.

Mind the data lag

Reports have a data lag due to processing time:

• Production environment: 1-hour lag. A report generated at 9:00 AM includes transactions up to 8:00 AM.
• Sandbox environment: 8-hour lag. A report generated at 9:00 AM includes transactions up to 1:00 AM.

API

If you try to create a schedule when one already exists, you receive a 409 Conflict error. Delete or update the existing export schedule first.

To schedule a recurring report via API, use the following endpoints:

• POST /ledger/v1/report-schedules: Schedules a recurring report for a specific wallet. Use the id of the report from the response to update or delete the schedule.
• GET /ledger/v1/report-schedules/{scheduleId}: Retrieves a list of recurring report schedules created by the user.

Portal

1. On the Portal, go to the Transaction history section and in the Export wallet transactions form, click Recurring export.

2. Configure the exported report:

   • Recurrence:
     • Daily: a report will be generated daily.
     • Weekly: a report will be generated weekly. Here, select the day of the week when the report will be generated.
     • Monthly: a report will be generated monthly.
   • Send at:
     • Time: the time of day when the report will be generated.
     • Timezone: your timezone.
   

3. Click Create schedule. The report will be generated and sent to your email on a regular basis.

To modify an existing schedule, click the schedule in the list, then update its settings. To delete a schedule, click the schedule and select Delete.

Manage scheduled reports

To change an existing schedule, do the following:

API

Use the PUT /ledger/v1/report-schedules/{scheduleId} endpoint to update the schedule parameters of a recurring report.

Portal

1. Go to the Transaction history > Export transactions > Recurring export.

   

2. Click the pencil icon next to the schedule and change the settings.

3. Click Update schedule.

   

To delete a schedule, do the following:

API

Use the DELETE /ledger/v1/report-schedules/{scheduleId} endpoint to delete a recurring report for a specific wallet.

Portal

1. Go to the Transaction history > Export transactions > Recurring export.

   

2. Click the trash bin icon next to the schedule.

---

Report data

The downloadable reports are created in the CSV or JSON format.

Use the report data to check that balances, amounts, and fees match between your system and BVNK.

You can import the data into accounting tools for further analysis or open it in any spreadsheet editor.

Download link expiration

Report download links remain active for 24 hours after generation. After that, the report is no longer accessible. Download and save your reports promptly.

In the report, you can find the following data:

Field	Description
Account Name	Name of the BVNK account associated with the transaction.
Account Reference	Unique reference identifier for the account.
Date Created	Timestamp when the transaction was created.
Currency	Currency code of the transaction.
Transaction ID	Unique identifier for the transaction.
Transaction Type	Type of transaction. Possible values: - PAYOUT - PAYIN - FEE - internalTransfer - paymentOut - channelDeposit - reversal
Description	Human-readable description of the transaction.
Amount	Transaction amount.
Transaction Hash	Blockchain transaction hash for crypto transactions.
Transaction UUID	Universally unique identifier for the transaction.
Payment Type	Type of payment: incoming (IN) or outgoing (OUT).
Payment Status	Current status of the payment. Possible values: - PENDING - COMPLETE - CANCELLED - EXPIRED - UNDERPAID
Merchant Reference	Reference identifier provided by the merchant.
From Currency Code	Source currency code for currency conversion transactions.
To Currency Code	Destination currency code for currency conversion transactions.
Merchant ID	Unique identifier for your BVNK account. In the Direct model, this matches the Account ID and identifies the account that uses BVNK services directly.
Running Balance	Cumulative balance after the transaction.
Transaction Context	Additional context or metadata for the transaction.
Wallet Lsid	Wallet ledger identifier.
Wallet Id	Unique identifier for the wallet.
Wallet Description	Human-readable description of the wallet.
Required Amount	Amount required for the transaction.
Paid Actual Amount	Actual amount that was paid.
Paid Amount Currency	Currency code of the paid amount.
Transaction Amount	Total transaction amount.
Display Currency	Currency code used for display purposes.
Exchange Rate	Exchange rate applied for currency conversion.
Display Actual Amount	Actual amount displayed in the display currency.
Display Required Amount	Required amount displayed in the display currency.
Counterparty Details	Information about the counterparty in the transaction.
Contact Name	Name of the contact associated with the transaction.
Customer Id	Unique identifier for the customer. In the Embedded model, this identifies your customers who use BVNK services via your account.
Country Code	ISO country code associated with the transaction.

---

Reconcile your records

After generating a report, compare it with your internal transaction records:

1. Match transactions: Use Transaction ID, Transaction UUID, or Merchant Reference to match BVNK transactions with your records.

2. Verify amounts: Compare Amount, Transaction Amount, and Running Balance fields with your records.

3. Check statuses: Verify that Payment Status matches your system's status. Investigate any PENDING or UNDERPAID transactions.

4. Reconcile fees: Compare fee amounts in your records with BVNK's fee calculations.

5. Handle discrepancies: If you find mismatches:

   • Verify the date range of your report
   • Check for transactions that may be in different statuses
   • Contact BVNK support if discrepancies persist

---

See also

To learn how to receive reconciliation reports via webhook delivery instead of email, see Receive transactions report via webhook.