Fetch a Transfer Attempt

Overview

Fetch the details of a single Transfer Attempt by its unique ID. Use this endpoint to retrieve complete information about a specific payment attempt, including its state, failure details, and associated buyer information.

Resource Access

User Permissions: Admin users only
Endpoint: GET /transfer_attempts/\{transfer_attempt_id}

Arguments

Parameter	Type	Required	Description
transfer_attempt_id	string	Yes (path)	The unique ID of the Transfer Attempt

Example Request

curl -X GET \
  'https://api.ahrvo.network/payments/na/transfer_attempts/TAattempt001' \
  -u username:password \
  -H 'Content-Type: application/json'

Example Response

{
  "id": "TAattempt001",
  "created_at": "2023-12-10T15:30:00Z",
  "amount": 9900,
  "currency": "USD",
  "state": "SUCCEEDED",
  "entity_id": "CFcheckoutForm123",
  "entity_type": "CHECKOUT_FORM",
  "transfer_id": "TRtransfer456",
  "payment_instrument_id": "PIcreditCard789",
  "failure_code": null,
  "failure_message": null,
  "buyer_details": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1-555-123-4567",
    "shipping_address": {
      "line1": "123 Main St",
      "line2": "Apt 4B",
      "city": "San Francisco",
      "region": "CA",
      "postal_code": "94102",
      "country": "USA"
    }
  },
  "tags": {
    "product": "premium_subscription",
    "campaign": "holiday_sale_2023",
    "referral_code": "FRIEND20",
    "customer_tier": "vip"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/transfer_attempts/TAattempt001"
    },
    "transfer": {
      "href": "https://api.ahrvo.network/payments/na/transfers/TRtransfer456"
    },
    "checkout_form": {
      "href": "https://api.ahrvo.network/payments/na/checkout_forms/CFcheckoutForm123"
    },
    "payment_instrument": {
      "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIcreditCard789"
    }
  }
}

Example Failed Attempt Response

{
  "id": "TAattempt002",
  "created_at": "2023-12-10T14:15:00Z",
  "amount": 9900,
  "currency": "USD",
  "state": "FAILED",
  "entity_id": "PLpaymentLink456",
  "entity_type": "PAYMENT_LINK",
  "transfer_id": null,
  "payment_instrument_id": "PIcreditCard012",
  "failure_code": "CARD_DECLINED",
  "failure_message": "The card was declined by the issuing bank. Please try a different payment method or contact your bank.",
  "buyer_details": {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+1-555-987-6543"
  },
  "tags": {
    "product": "one_time_purchase"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/transfer_attempts/TAattempt002"
    },
    "payment_link": {
      "href": "https://api.ahrvo.network/payments/na/payment_links/PLpaymentLink456"
    },
    "payment_instrument": {
      "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIcreditCard012"
    }
  }
}

Additional Information

State: Current status of the payment attempt
- SUCCEEDED: Payment completed successfully
  - transfer_id contains the resulting Transfer
  - Customer was charged
  - Funds captured
- FAILED: Payment failed
  - failure_code and failure_message explain why
  - No Transfer created
  - Customer not charged
- PENDING: Payment being processed
  - Awaiting processor confirmation
  - May take seconds (card) or days (ACH)
  - Will transition to SUCCEEDED or FAILED
Transfer ID: Link to successful payment
- null: If state is FAILED or PENDING
- Populated: If state is SUCCEEDED
- Use to retrieve full Transfer details
- Transfer contains complete transaction info
Failure Details: Why payment failed (if state = FAILED)
- failure_code: Machine-readable error code
- failure_message: Human-readable explanation
- Common failure codes:
  - CARD_DECLINED: Bank declined the card
  - INSUFFICIENT_FUNDS: Not enough balance
  - INVALID_CARD_NUMBER: Card number invalid
  - CARD_EXPIRED: Card past expiration date
  - CVV_MISMATCH: Security code incorrect
  - ADDRESS_VERIFICATION_FAILED: AVS check failed
  - LIMIT_EXCEEDED: Transaction exceeds limit
  - FRAUD_DETECTED: Flagged by fraud system
  - PROCESSING_ERROR: Technical processor error
Amount: Payment amount in cents
- Example: 9900 = $99.00
- Same as checkout form/payment link amount
- In smallest currency unit
Entity Type: Source of the attempt
- CHECKOUT_FORM: Embedded checkout page
- PAYMENT_LINK: Shareable payment link
- PAYOUT_LINK: Payout/disbursement link
Buyer Details: Customer information
- name: Customer's full name
- email: Email address (for receipts, support)
- phone: Phone number (optional)
- shipping_address: Delivery address (if applicable)
- Collected during checkout process
- Used for receipts, shipping, support
Payment Instrument ID: Payment method used
- Credit card, debit card, or bank account
- Links to Payment Instrument resource
- null if payment method not saved
Tags: Custom metadata
- Track campaigns, products, referrals
- Filter and group attempts
- Business intelligence and analytics
Use Cases:
- Customer Support: Help customer with payment issue
  - Customer calls about failed payment
  - Lookup attempt by email or ID
  - Explain failure reason
  - Guide to resolution (e.g., "Try different card")
- Order Fulfillment: Verify payment before shipping
  - Order placed via checkout form
  - Check attempt state = SUCCEEDED
  - Verify transfer_id exists
  - Proceed with shipment
- Failed Payment Recovery: Follow up on failures
  - Identify failed attempt
  - Read failure_code and failure_message
  - Send targeted recovery email
  - Example: CARD_DECLINED → "Update your payment method"
- Fraud Investigation: Review suspicious attempts
  - Multiple failed attempts from same buyer
  - Unusual amount or pattern
  - Check buyer_details and tags
  - Flag for manual review
- Conversion Funnel Analysis: Understand checkout flow
  - Track time from checkout start to attempt
  - Measure drop-off points
  - Identify friction in payment flow
- Receipt Generation: Send payment confirmation
  - Fetch successful attempt details
  - Include buyer_details and amount
  - Generate and email receipt
  - Link to Transfer for full details
Common Workflows:
- Successful Payment:
  1. Customer completes checkout
  2. Transfer Attempt created (state: PENDING)
  3. Processor confirms (state: SUCCEEDED)
  4. Transfer created (transfer_id populated)
  5. Fetch attempt to verify success
  6. Send confirmation email with receipt
- Failed Payment Recovery:
  1. Transfer Attempt fails (state: FAILED)
  2. Fetch attempt to get failure details
  3. Analyze failure_code
  4. Send recovery email:
    - CARD_DECLINED: "Try different card"
    - INSUFFICIENT_FUNDS: "Check available balance"
    - CARD_EXPIRED: "Update card expiration"
  5. Customer retries with corrected info
- Pending ACH Payment:
  1. Customer pays via bank account
  2. Transfer Attempt created (state: PENDING)
  3. ACH processing takes 3-5 days
  4. Poll attempt or wait for webhook
  5. State changes to SUCCEEDED or FAILED
  6. If SUCCEEDED, fulfill order
Related Links (in _links):
- transfer: The resulting Transfer (if successful)
- checkout_form: The checkout form used
- payment_link: The payment link used
- payout_link: The payout link used (if applicable)
- payment_instrument: Payment method details
Timing Information:
- created_at: When attempt was created
- Time to success/failure varies:
  - Credit cards: Seconds
  - Debit cards: Seconds to minutes
  - ACH: 3-5 business days
  - Wire transfers: Same day to 1 day
Best Practices:
- Webhook Integration: Listen for state changes
  - Don't poll repeatedly
  - Use transfer_attempt.succeeded webhook
  - Use transfer_attempt.failed webhook
- Error Handling: Display helpful messages
  - Parse failure_code for specific guidance
  - Show customer-friendly failure_message
  - Offer alternative payment methods
- Receipt Storage: Save attempt ID with orders
  - Link orders to attempts in your database
  - Easy lookup for support
  - Audit trail for disputes
- Retry Logic: Allow customers to retry
  - Keep attempt history
  - Identify chronic issues (same failure repeatedly)
  - Suggest alternatives after multiple failures
Security Considerations:
- Attempt IDs are sensitive
- Contains customer PII (email, phone, address)
- Protect access with proper authentication
- Log access for audit purposes
Related Endpoints:
- GET /transfer_attempts: List all attempts
- GET /transfers/{id}: View resulting Transfer
- GET /checkout_forms/{entity_id}: View checkout form
- GET /payment_links/{entity_id}: View payment link
- GET /payment_instruments/{id}: View payment method details

Overview​

Resource Access​

Arguments​

Example Request​

Example Response​

Example Failed Attempt Response​

Additional Information​