List Transfers

Overview

Retrieve a paginated list of all Transfers. Filter by merchant, date range, state, type, and more to find specific payments.

Resource Access

User Permissions: Admin users only
Endpoint: GET /transfers

Arguments

Parameter	Type	Required	Description
limit	integer	No	Number of results per page (default: 20, max: 100)
after_cursor	string	No	Cursor for next page
before_cursor	string	No	Cursor for previous page
merchant	string	No	Filter by Merchant ID
state	string	No	Filter by state (PENDING, SUCCEEDED, FAILED)
type	string	No	Filter by type (DEBIT, CREDIT, REVERSAL)
created_at.gte	string	No	Created after date (ISO 8601)
created_at.lte	string	No	Created before date (ISO 8601)
amount.gte	integer	No	Minimum amount in cents
amount.lte	integer	No	Maximum amount in cents
tags	object	No	Filter by custom tags

Example Request

curl -X GET \
  'https://api.ahrvo.network/payments/na/transfers?merchant=MUmerchant123&state=SUCCEEDED&limit=50' \
  -u username:password

Example Response

{
  "_embedded": {
    "transfers": [
      {
        "id": "TRtransfer789",
        "created_at": "2023-12-10T20:00:00Z",
        "updated_at": "2023-12-10T20:00:15Z",
        "amount": 10000,
        "currency": "USD",
        "state": "SUCCEEDED",
        "type": "DEBIT",
        "merchant": "MUmerchant123",
        "source": "PIcreditCard456",
        "destination": null,
        "fee": 320,
        "tags": {
          "order_id": "ORD-2023-12345",
          "product": "subscription"
        },
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/transfers/TRtransfer789"
          }
        }
      },
      {
        "id": "TRtransfer790",
        "created_at": "2023-12-10T19:45:00Z",
        "updated_at": "2023-12-10T19:45:10Z",
        "amount": 4999,
        "currency": "USD",
        "state": "SUCCEEDED",
        "type": "DEBIT",
        "merchant": "MUmerchant123",
        "source": "PIdebitCard222",
        "destination": null,
        "fee": 175,
        "tags": {
          "order_id": "ORD-2023-12340",
          "product": "one-time"
        },
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/transfers/TRtransfer790"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/transfers?merchant=MUmerchant123&state=SUCCEEDED&limit=50"
    },
    "next": {
      "href": "https://api.ahrvo.network/payments/na/transfers?merchant=MUmerchant123&state=SUCCEEDED&limit=50&after_cursor=dHJhbnNmZXI3OTA"
    }
  },
  "page": {
    "limit": 50,
    "offset": 0,
    "count": 2
  }
}

Additional Information

Pagination: Cursor-based
- after_cursor: Get next page
- before_cursor: Get previous page
- limit: Results per page (default: 20, max: 100)
- Follow _links.next for next page
State Filters:
- PENDING: Transfer submitted, awaiting processor
- SUCCEEDED: Funds successfully transferred
- FAILED: Transfer failed
- Omit to get all states
Type Filters:
- DEBIT: Customer charges
- CREDIT: Merchant payouts
- REVERSAL: Refunds/reversals
- Omit to get all types
Date Filtering: ISO 8601 timestamps
- created_at.gte: Start date (inclusive)
- created_at.lte: End date (inclusive)
- Example: 2023-12-01T00:00:00Z
- Useful for daily/monthly reports
Amount Filtering: In cents
- amount.gte: Minimum amount
- amount.lte: Maximum amount
- Example: amount.gte=10000 for $100+
- Useful for finding large transactions
Tag Filtering: Custom metadata
- Filter by any tag key-value
- Example: tags[order_id]=ORD-123
- Multiple tags = AND logic
- Useful for tracking campaigns, products
Merchant Filtering: Single merchant only
- Specify Merchant ID
- Cannot filter multiple merchants in one request
- Platform users can see all merchants
Sorting: Always by creation date
- Newest first by default
- Cannot change sort order
- Use cursors for pagination
Performance: Large date ranges may be slow
- Narrow filters for better performance
- Use specific merchant + date range
- Consider caching results
Count: Total count not provided
- Paginate through all results for full count
- Use cursors until no next link
- Consider alternative counting methods

Use Cases

Daily Transaction Report

curl -X GET \
  'https://api.ahrvo.network/payments/na/transfers?merchant=MUmerchant123&created_at.gte=2023-12-10T00:00:00Z&created_at.lte=2023-12-10T23:59:59Z&state=SUCCEEDED&limit=100' \
  -u username:password

All successful transactions for December 10
Merchant-specific
Up to 100 per page

Failed Payments Investigation

curl -X GET \
  'https://api.ahrvo.network/payments/na/transfers?merchant=MUmerchant123&state=FAILED&created_at.gte=2023-12-01T00:00:00Z' \
  -u username:password

All failed transfers since December 1
Analyze failure patterns
Identify customer issues

High-Value Transactions

curl -X GET \
  'https://api.ahrvo.network/payments/na/transfers?amount.gte=100000&state=SUCCEEDED' \
  -u username:password

All successful transfers ≥ $1,000
Monitor large transactions
Fraud detection

Campaign Performance

curl -X GET \
  'https://api.ahrvo.network/payments/na/transfers?tags[campaign]=holiday_2023&state=SUCCEEDED' \
  -u username:password

All successful payments for holiday campaign
Track campaign revenue
Calculate conversion rates

Monthly Payout Summary

curl -X GET \
  'https://api.ahrvo.network/payments/na/transfers?merchant=MUmerchant123&type=CREDIT&created_at.gte=2023-12-01T00:00:00Z&created_at.lte=2023-12-31T23:59:59Z' \
  -u username:password

All payouts to merchant in December
Monthly reconciliation
Settlement verification

Best Practices

Filter Early: Use specific filters
- Merchant + date range minimum
- Reduces response size
- Improves performance
Pagination: Process page by page
- Don't request all at once
- Follow next links
- Stop when no next link
Caching: Cache results when appropriate
- Historical data won't change
- Yesterday's transactions are final
- Reduce API calls
Rate Limits: Respect API limits
- Don't paginate too quickly
- Implement exponential backoff
- Consider batch processing
Date Ranges: Keep reasonable
- 1-30 days ideal
- Longer ranges may timeout
- Split into smaller requests
Error Handling: Handle empty results
- _embedded.transfers may be empty
- Check page.count
- Display appropriate message
Tag Conventions: Use consistent tags
- Standard naming (snake_case)
- Document tag schema
- Easier filtering and reporting

Common Workflows

Generate Daily Report

Calculate date range (yesterday)
List transfers with date filter
Filter by SUCCEEDED state
Paginate through all results
Calculate totals (sum amounts, count transactions)
Export to CSV/Excel

Reconcile Merchant Account

Get merchant's settlement period
List SUCCEEDED transfers for period
List CREDIT transfers (payouts)
Calculate net amount
Compare to settlement amounts
Identify discrepancies

Find Refunded Transaction

Get original transfer ID
List transfers filtered by tags
Or use GET /transfers/{id}/reversals
Check reversal amount matches
Verify reversal succeeded

Pagination Loop (All Results)

let allTransfers = [];
let cursor = null;

do {
  const url = cursor 
    ? `/transfers?merchant=MU123&after_cursor=${cursor}`
    : `/transfers?merchant=MU123`;
  
  const response = await fetch(url);
  const data = await response.json();
  
  allTransfers.push(...data._embedded.transfers);
  cursor = data._links.next ? extractCursor(data._links.next.href) : null;
} while (cursor);

console.log(`Total transfers: ${allTransfers.length}`);

POST /transfers: Create a transfer
GET /transfers/{id}: Fetch specific transfer
PUT /transfers/{id}: Update transfer tags
POST /transfers/{id}/reversals: Create refund
GET /transfers/{id}/reversals: List refunds

Overview​

Resource Access​

Arguments​

Example Request​

Example Response​

Additional Information​

Use Cases​

Daily Transaction Report​

Failed Payments Investigation​

High-Value Transactions​

Campaign Performance​

Monthly Payout Summary​

Best Practices​

Common Workflows​

Generate Daily Report​

Reconcile Merchant Account​

Find Refunded Transaction​

Pagination Loop (All Results)​

Related Endpoints​

Overview

Resource Access

Arguments

Example Request

Example Response

Additional Information

Use Cases

Daily Transaction Report

Failed Payments Investigation

High-Value Transactions

Campaign Performance

Monthly Payout Summary

Best Practices

Common Workflows

Generate Daily Report

Reconcile Merchant Account

Find Refunded Transaction

Pagination Loop (All Results)

Related Endpoints