SPEI Transactions API — V1 to V2 Migration Guide

Why Migrate?

The V1 SPEI Transactions API (/spei/v1/deposits and /spei/v1/withdrawals) uses offset-based pagination, which suffers from increasing latency as you paginate deeper into large result sets. Clients performing reconciliation over wide date ranges have experienced significant slowdowns on V1.

The V2 APIs resolve these performance issues by replacing offset pagination with token-based pagination. These changes bring many benefits:

• Consistent performance: response times remain stable regardless of how deep you paginate. Latency spikes are not expected with the new APIs.
• Incremental synchronization: you can resume from the last token without re-fetching earlier pages.
• Cleaner response format: response payloads were improved to contain the most relevant and useful data for the deposits and withdrawals.
• Bidirectional refund linking: both deposits and withdrawals include cross-references to their counterpart, simplifying refund reconciliation.

---

Endpoint Mapping

---

Pagination Details

The V1 API responses included page, page_size, total_pages, and total_elements. With the V2, these fields were deprecated, and the new response includes a next_page_token field.

Pass it as page_token in the next request to retrieve the following page. When next_page_token is absent, you have reached the end of the collection.

📘

Opaque page tokens

The page_token values are opaque. Do not parse, decode, or construct them. They are only valid for the original query parameters — changing filters while reusing a token produces undefined behavior.

---

Deposits

Removed Query Parameters

The following V1 query parameters have been removed in V2 and have no direct equivalent:

Query Parameter Equivalents

The following V1 query parameters have a direct or renamed equivalent in V2:

Removed Response Fields

The following V1 response fields have been removed in V2 and have no direct equivalent:

Response Field Equivalents

The V1 response nests most transaction metadata inside a details object. V2 promotes these fields to the top level for a flatter, more ergonomic structure.

New Fields in V2

The following fields are new in V2 and were not available in V1:

The V1 field details.multiclabe_validation_error has been deprecated. In V2, deposit errors are now defined in the errors field, which provides structured error information with a code and message for each error. The complete error catalogue can be found in the API Reference.

---

Withdrawals

Removed Query Parameters

The following V1 query parameters have been removed in V2 and have no direct equivalent:

Query Parameter Equivalents

The following V1 query parameters have a direct or renamed equivalent in V2:

Removed Response Fields

The following V1 response fields have been removed in V2 and have no direct equivalent:

Response Field Equivalents

The V1 response nests most transaction metadata inside a details object. V2 promotes these fields to the top level and replaces the embedded full deposit object with a lightweight reference.

New Fields in V2

The following fields are new in V2 and were not available in V1:

---

Refund Reconciliation

When a withdrawal fails, the banking system may issue a compensatory deposit back to the sender.

V2 Approach

V2 provides bidirectional linking with lightweight references on both sides:

• A withdrawal includes a refunded_deposit object with the compensatory deposit's fid and tracking_key.
• A deposit includes a refunded_withdrawal object with the original withdrawal's wid, tracking_key, and origin_id.

V2 Withdrawal                     V2 Deposit
┌─────────────────────────┐       ┌─────────────────────────┐
│ wid: "w-123"            │       │ fid: "d-456"            │
│ status: "FAILED"        │       │ status: "COMPLETE"      │
│ refunded_deposit: {     │──────▶│ refunded_withdrawal: {  │
│   fid: "d-456"          │       │   wid: "w-123"          │
│   tracking_key: "..."   │◀──────│   tracking_key: "..."   │
│ }                       │       │   origin_id: "a261847a" │
└─────────────────────────┘       │ }                       │
                                  └─────────────────────────┘

To reconcile refunds in V2:

1. Starting from withdrawals: Search the refunded withdrawals, using the only_refunds param. Each result contains a refunded_deposit with the fid and tracking_key of the compensatory deposit. These two fields allow us to match the deposit that was created to compensate the withdrawal.

2. Starting from deposits: Search the refunded deposits, using the only_refunds param. Each result contains a refunded_withdrawal with the wid, tracking_key, and origin_id of the compensated withdrawal. These three fields allow us to match the withdrawal that originated the compensatory deposit.