Fetch a Transfer

Overview

Retrieve detailed information about a specific Transfer by its ID. View payment status, amounts, fees, and metadata.

Resource Access

User Permissions: Admin users only
Endpoint: GET /transfers/\{transfer_id}

Arguments

Parameter	Type	Required	Description
transfer_id	string	Yes	Unique Transfer ID (in URL path)

Example Request

curl -X GET \
  'https://api.ahrvo.network/payments/na/transfers/TRtransfer789' \
  -u username:password

Example Response (Successful Charge)

{
  "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,
  "ready_to_settle_at": "2023-12-10T20:00:15Z",
  "trace_id": "TRC_98765432",
  "tags": {
    "order_id": "ORD-2023-12345",
    "product": "subscription",
    "customer_tier": "premium"
  },
  "messages": [],
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/transfers/TRtransfer789"
    },
    "merchant": {
      "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchant123"
    },
    "payment_instrument": {
      "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIcreditCard456"
    },
    "reversals": {
      "href": "https://api.ahrvo.network/payments/na/transfers/TRtransfer789/reversals"
    }
  }
}

Example Response (Failed Transfer)

{
  "id": "TRtransfer790",
  "created_at": "2023-12-10T19:30:00Z",
  "updated_at": "2023-12-10T19:30:05Z",
  "amount": 5000,
  "currency": "USD",
  "state": "FAILED",
  "type": "DEBIT",
  "merchant": "MUmerchant123",
  "source": "PIcreditCard789",
  "destination": null,
  "fee": 0,
  "ready_to_settle_at": null,
  "trace_id": "TRC_98765433",
  "tags": {
    "order_id": "ORD-2023-12346"
  },
  "messages": [
    {
      "code": "CARD_DECLINED",
      "message": "The card was declined by the issuing bank",
      "details": "Insufficient funds"
    }
  ],
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/transfers/TRtransfer790"
    },
    "merchant": {
      "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchant123"
    },
    "payment_instrument": {
      "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIcreditCard789"
    }
  }
}

Example Response (Split Transfer)

{
  "id": "TRtransfer791",
  "created_at": "2023-12-10T18:00:00Z",
  "updated_at": "2023-12-10T18:00:12Z",
  "amount": 10000,
  "currency": "USD",
  "state": "SUCCEEDED",
  "type": "DEBIT",
  "merchant": "MUplatform",
  "source": "PIbuyer_card",
  "destination": null,
  "fee": 320,
  "ready_to_settle_at": "2023-12-10T18:00:12Z",
  "trace_id": "TRC_98765434",
  "split_transfers": [
    {
      "id": "TRsplit_001",
      "merchant": "MUvendor_a",
      "amount": 7500,
      "fee": 240,
      "tags": {"vendor": "A"}
    },
    {
      "id": "TRsplit_002",
      "merchant": "MUvendor_b",
      "amount": 2500,
      "fee": 80,
      "tags": {"vendor": "B"}
    }
  ],
  "tags": {
    "marketplace_order": "MP-12345"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/transfers/TRtransfer791"
    },
    "split_transfers": [
      {
        "href": "https://api.ahrvo.network/payments/na/transfers/TRsplit_001"
      },
      {
        "href": "https://api.ahrvo.network/payments/na/transfers/TRsplit_002"
      }
    ]
  }
}

Additional Information

Transfer ID: Unique identifier
- Starts with "TR"
- Immutable
- Reference for refunds, support
- Store in your database
State: Current status
- PENDING: Awaiting processor
  - Typical: Few seconds for cards
  - Can take minutes during high load
  - ACH: 3-5 business days
- SUCCEEDED: Funds transferred
  - Customer charged successfully
  - Merchant will receive in settlement
- FAILED: Transfer failed
  - Check messages for details
  - No funds moved
  - Customer should retry
Type: Direction of funds
- DEBIT: Customer → Merchant (charge)
- CREDIT: Platform → Merchant (payout)
- REVERSAL: Merchant → Customer (refund)
Amount: Total transfer amount
- In cents
- Example: 10000 = $100.00
- Does NOT include fees
- Gross amount customer pays
Fee: Platform processing fee
- In cents
- Deducted from merchant's settlement
- Example: $100 charge, $3.20 fee → Merchant nets $96.80
- 0 for failed transfers
Currency: Three-letter code
- Default: "USD"
- Currently only USD supported
- Future: Multi-currency
Source: Where funds came from
- Payment Instrument ID
- Customer's card or bank account
- Present for DEBIT transfers
- Null for CREDIT transfers
Destination: Where funds go to
- Payment Instrument ID
- Merchant's bank account
- Present for CREDIT transfers (payouts)
- Null for DEBIT transfers
Merchant: Merchant resource
- ID of merchant
- Who receives (DEBIT) or sends (CREDIT) funds
- Links to full merchant details
Ready to Settle At: When available for settlement
- ISO 8601 timestamp
- Typically immediately after SUCCEEDED
- Null for PENDING/FAILED
- Used by settlement batching
Trace ID: Processor reference
- External transaction ID
- Use for support with processor
- Helps troubleshoot issues
Tags: Custom metadata
- Your key-value data
- Track orders, campaigns, etc.
- Not visible to customers
- Searchable via list endpoint
Messages: Error/info messages
- Array of message objects
- Present for FAILED transfers
- Contains error codes and details
- Show to customer or support
Split Transfers: Sub-transfers
- Array of splits
- Each has own ID, merchant, amount, fee
- Used in marketplace scenarios
- Sum may be less than total (platform keeps difference)
Links: Related resources
- merchant: Full merchant details
- payment_instrument: Card/bank details
- reversals: List of refunds
- split_transfers: Individual split details

Use Cases

Order Status Page

// Customer views order status
const transfer = await fetchTransfer('TRtransfer789');

if (transfer.state === 'SUCCEEDED') {
  showSuccess('Payment processed successfully');
} else if (transfer.state === 'PENDING') {
  showPending('Payment is processing...');
} else if (transfer.state === 'FAILED') {
  const error = transfer.messages[0];
  showError(`Payment failed: ${error.message}`);
}

Customer Support Inquiry

# Customer: "Where's my refund?"
# Support: Look up original transfer

curl -X GET \
  'https://api.ahrvo.network/payments/na/transfers/TRtransfer789' \
  -u username:password

# Check for reversals link
# GET /transfers/TRtransfer789/reversals

Webhook Processing

// Webhook: transfer.succeeded
app.post('/webhooks/finix', (req, res) => {
  const transferId = req.body.data.id;
  
  // Fetch full details
  const transfer = await fetchTransfer(transferId);
  
  // Update order in database
  await updateOrder(transfer.tags.order_id, {
    status: 'paid',
    payment_id: transfer.id,
    amount: transfer.amount,
    fee: transfer.fee
  });
  
  // Send confirmation email
  await sendConfirmation(transfer.tags.customer_email);
  
  res.status(200).send('OK');
});

Marketplace Revenue Split

// Platform admin views transaction
const transfer = await fetchTransfer('TRtransfer791');

console.log(`Total: $${transfer.amount / 100}`);
console.log('Splits:');
transfer.split_transfers.forEach(split => {
  const net = split.amount - split.fee;
  console.log(`  ${split.merchant}: $${net / 100} (net)`);
});

const platformFee = transfer.fee;
const vendorFees = transfer.split_transfers.reduce(
  (sum, s) => sum + s.fee, 0
);
console.log(`Platform revenue: $${(platformFee - vendorFees) / 100}`);

Failed Payment Recovery

// Analyze failed transfer
const transfer = await fetchTransfer('TRtransfer790');

if (transfer.state === 'FAILED') {
  const errorCode = transfer.messages[0].code;
  
  switch (errorCode) {
    case 'CARD_DECLINED':
      // Suggest trying different card
      promptCustomer('Try a different payment method');
      break;
    case 'INSUFFICIENT_FUNDS':
      // Suggest lower amount or different card
      offerPaymentPlan();
      break;
    case 'CARD_EXPIRED':
      // Request updated card info
      requestCardUpdate();
      break;
    default:
      // Generic error
      contactSupport();
  }
}

Best Practices

Store Transfer ID: Save in your database
- Reference for customer support
- Link to orders
- Track payment history
Poll Carefully: For PENDING transfers
- Use webhooks instead of polling
- If polling: Exponential backoff
- Max poll time: 5 minutes
- After 5 minutes, consider failed
Error Messages: Display to customer
- Read from messages array
- Provide helpful context
- Suggest next steps
- Don't expose trace_id to customer
Webhooks: Listen for state changes
- transfer.succeeded
- transfer.failed
- More reliable than polling
- Process asynchronously
Idempotency: Transfer already created
- Fetch to check status
- Don't create duplicate
- Use transfer ID from initial creation
Links: Follow for related data
- reversals: Check for refunds
- payment_instrument: Get card details
- merchant: Get merchant info
- Reduces need for multiple endpoints

Common Workflows

Check Payment Status

Create transfer
Store transfer ID
If PENDING: Listen for webhook
Webhook received: Fetch transfer
Check state
Update order accordingly

Customer Refund Request

Customer provides order number
Look up order in database
Get transfer ID from order
Fetch transfer details
Verify transfer SUCCEEDED
Create reversal
Confirm refund to customer

Reconciliation

List settlements for period
For each settlement entry
Fetch transfer details
Verify amounts match
Check for reversals
Calculate net amounts
Compare to bank deposits

POST /transfers: Create a transfer
GET /transfers: List all transfers
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 (Successful Charge)​

Example Response (Failed Transfer)​

Example Response (Split Transfer)​

Additional Information​

Use Cases​

Order Status Page​

Customer Support Inquiry​

Webhook Processing​

Marketplace Revenue Split​

Failed Payment Recovery​

Best Practices​

Common Workflows​

Check Payment Status​

Customer Refund Request​

Reconciliation​

Related Endpoints​

Overview

Resource Access

Arguments

Example Request

Example Response (Successful Charge)

Example Response (Failed Transfer)

Example Response (Split Transfer)

Additional Information

Use Cases

Order Status Page

Customer Support Inquiry

Webhook Processing

Marketplace Revenue Split

Failed Payment Recovery

Best Practices

Common Workflows

Check Payment Status

Customer Refund Request

Reconciliation

Related Endpoints