Skip to main content

Update a Transfer

Overview​

Update the metadata tags on an existing Transfer. Use this to add custom tracking information after a transfer is created.

Resource Access​

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

Arguments​

ParameterTypeRequiredDescription
transfer_idstringYesUnique Transfer ID (in URL path)
tagsobjectYesCustom key-value metadata to update

Example Request​

curl -X PUT \
  'https://api.ahrvo.network/payments/na/transfers/TRtransfer789' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": {
      "order_id": "ORD-2023-12345",
      "product": "subscription",
      "customer_tier": "premium",
      "fulfillment_status": "shipped",
      "tracking_number": "1Z999AA10123456784"
    }
  }'

Example Response​

{
  "id": "TRtransfer789",
  "created_at": "2023-12-10T20:00:00Z",
  "updated_at": "2023-12-11T10:30:00Z",
  "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",
    "fulfillment_status": "shipped",
    "tracking_number": "1Z999AA10123456784"
  },
  "_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"
    }
  }
}

Additional Information​

  • Tags Only: Cannot change amount, state, or other fields
    • Only tags field is mutable
    • All other fields are immutable after creation
    • Amount, merchant, payment instrument locked
    • Use reversals to refund, not updates
  • Complete Replacement: Tags are replaced, not merged
    • New tags object REPLACES old tags
    • Existing tags not in request are DELETED
    • Always send complete tags object
    • Example: Old tags {a: 1, b: 2}, Update with {c: 3} → Result: {c: 3}
  • Tag Limits:
    • Keys: Alphanumeric, underscore, hyphen
    • Values: Strings only
    • Max key length: 100 characters
    • Max value length: 500 characters
    • Max tags per transfer: 50
  • Updated At: Timestamp changes
    • updated_at reflects last modification
    • Original created_at unchanged
    • Use to track when tags were added
  • Use Cases:
    • Add fulfillment status after shipping
    • Link to external systems after processing
    • Tag with customer support ticket
    • Mark for accounting/reporting
    • Add campaign attribution retroactively
  • Idempotency: Safe to retry
    • Same tags = same result
    • No side effects
    • Can update multiple times
  • Search: Tags are searchable
    • Use GET /transfers with tag filters
    • Find transfers by custom criteria
    • Group by campaign, product, etc.
  • No Validation: System doesn't validate tag content
    • Any string values accepted
    • No schema enforcement
    • Your responsibility to maintain consistency
    • Consider documenting tag conventions

Use Cases​

Add Tracking After Shipment​

# Order shipped, add tracking number
curl -X PUT \
  'https://api.ahrvo.network/payments/na/transfers/TRtransfer789' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": {
      "order_id": "ORD-2023-12345",
      "product": "widget",
      "fulfillment_status": "shipped",
      "tracking_number": "1Z999AA10123456784",
      "carrier": "UPS",
      "shipped_at": "2023-12-11T10:00:00Z"
    }
  }'
# Customer opens support ticket about payment
curl -X PUT \
  'https://api.ahrvo.network/payments/na/transfers/TRtransfer790' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": {
      "order_id": "ORD-2023-12346",
      "support_ticket": "TICKET-5678",
      "issue": "customer_inquiry",
      "assigned_to": "agent_jane"
    }
  }'

Add Campaign Attribution​

# Retroactively tag with marketing campaign
curl -X PUT \
  'https://api.ahrvo.network/payments/na/transfers/TRtransfer791' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": {
      "order_id": "ORD-2023-12347",
      "campaign": "holiday_2023",
      "channel": "email",
      "utm_source": "newsletter",
      "utm_medium": "email",
      "utm_campaign": "holiday_sale"
    }
  }'

Mark for Accounting Review​

# Flag high-value transaction for review
curl -X PUT \
  'https://api.ahrvo.network/payments/na/transfers/TRtransfer792' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": {
      "order_id": "ORD-2023-12348",
      "product": "enterprise_license",
      "accounting_status": "pending_review",
      "reviewer": "accounting_dept",
      "amount_category": "high_value",
      "review_required": "true"
    }
  }'

Best Practices​

  • Include Existing Tags: Always send complete tags 
    // WRONG: Will delete existing tags
    await updateTransfer(id, {
      tags: { tracking_number: '123' }
    });

    // RIGHT: Include existing tags
    const transfer = await fetchTransfer(id);
    await updateTransfer(id, {
      tags: {
        ...transfer.tags,
        tracking_number: '123'
      }
    });
  • Tag Naming Conventions: Use consistent naming
    • snake_case for keys
    • Descriptive names
    • Avoid abbreviations
    • Document schema
    • Example: fulfillment_status not status
  • Timestamp Tags: Use ISO 8601
    • shipped_at: "2023-12-11T10:00:00Z"
    • Easier to parse and filter
    • Includes timezone
    • Sortable
  • Boolean Tags: Use strings
    • "true" or "false" not true or false
    • Tags are string-only
    • Consistent casing
    • Consider "yes"/"no" or "1"/"0"
  • Error Handling: Check response
    • Verify tags updated
    • Check updated_at changed
    • Validate critical tags
    • Retry on network errors
  • Audit Trail: Track tag changes
    • Log who updated and when
    • Store old values
    • Use for compliance
    • Helpful for debugging
  • Performance: Update sparingly
    • Not intended for frequent updates
    • Consider batching changes
    • Use webhooks instead of polling + updating

Common Workflows​

Fulfillment Integration​

  1. Payment succeeds
  2. Create order in fulfillment system
  3. Fulfillment system ships order
  4. Webhook from fulfillment system
  5. Update transfer with tracking info
  6. Send tracking email to customer

Customer Support Flow​

  1. Customer contacts support about payment
  2. Support agent looks up transfer by order ID
  3. Agent adds support ticket to tags
  4. Agent resolves issue
  5. Update tags with resolution
  6. Use for reporting and training

Marketing Attribution​

  1. Payment created without UTM tags
  2. Later, link payment to marketing campaign
  3. Update transfer with campaign tags
  4. Run reports on campaign performance
  5. Calculate ROI by campaign

Accounting Workflow​

  1. End of day: List all transfers
  2. For high-value transfers:
  3. Update with accounting_status tag
  4. Accountant reviews flagged transfers
  5. Update with approval status
  6. Export to accounting system
  • POST /transfers: Create a transfer
  • GET /transfers: List transfers (filter by tags)
  • GET /transfers/{id}: Fetch transfer details
  • POST /transfers/{id}/reversals: Create refund
  • GET /transfers/{id}/reversals: List refunds