Skip to main content

Create a Transfer

Overview​

Create a Transfer to move funds to or from a Payment Instrument. Transfers represent all payments in the platform, including charges, payouts, refunds, and reversals.

Resource Access​

  • User Permissions: Admin users only
  • Endpoint: POST /transfers

Arguments​

ParameterTypeRequiredDescription
amountintegerYesTransfer amount in cents
currencystringYesCurrency code (default: "USD")
merchantstringYesMerchant ID receiving/sending funds
sourcestringNo*Payment Instrument ID to charge (for debits)
destinationstringNo*Payment Instrument ID to credit (for payouts)
tagsobjectNoCustom key-value metadata
split_transfersarrayNoSplit payment among multiple merchants
additional_buyer_chargesobjectNoAdditional fees (e.g., convenience fees)
level_two_level_three_dataobjectNoEnhanced card data for lower interchange
operation_keystringNoCARD_PRESENT_SALE or CARD_NOT_PRESENT_SALE

*Either source OR destination is typically required depending on transfer type

Example Request (Charge Customer)​

curl -X POST \
  'https://api.ahrvo.network/payments/na/transfers' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 10000,
    "currency": "USD",
    "merchant": "MUmerchant123",
    "source": "PIcreditCard456",
    "tags": {
      "order_id": "ORD-2023-12345",
      "product": "subscription",
      "customer_tier": "premium"
    }
  }'

Example Response​

{
  "id": "TRtransfer789",
  "created_at": "2023-12-10T20:00:00Z",
  "amount": 10000,
  "currency": "USD",
  "state": "PENDING",
  "type": "DEBIT",
  "merchant": "MUmerchant123",
  "source": "PIcreditCard456",
  "destination": null,
  "fee": 320,
  "tags": {
    "order_id": "ORD-2023-12345",
    "product": "subscription",
    "customer_tier": "premium"
  },
  "_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​

  • Transfer Types (automatically determined):
    • DEBIT: Charge customer (source = customer's card/bank)
      • Merchant receives funds
      • Customer pays
      • Most common type
    • CREDIT: Payout to merchant/recipient (destination = recipient's bank)
      • Merchant/recipient receives funds
      • Platform sends funds
    • REVERSAL: Refund/reverse a previous transfer
      • Created via POST /transfers/{id}/reversals
      • Returns funds to customer
  • States:
    • PENDING: Transfer submitted, awaiting processor
    • SUCCEEDED: Funds successfully transferred
    • FAILED: Transfer failed (see error details)
  • Amount: In cents (smallest currency unit)
    • Example: 10000 = $100.00
    • Must be positive integer
    • Minimum varies by payment method
  • Fee: Platform/processing fee
    • Calculated automatically based on merchant's fee profile
    • Deducted from merchant's settlement
    • In cents
    • Example: $100 charge, $3.20 fee → Merchant nets $96.80
  • Source: Where funds come from
    • For DEBIT transfers (charges): Customer's payment instrument
    • Credit card ID, debit card ID, or bank account ID
    • Must be verified payment instrument
    • Required for charging customers
  • Destination: Where funds go to
    • For CREDIT transfers (payouts): Recipient's bank account
    • Bank account ID or debit card ID (for instant payouts)
    • Required for sending funds
  • Merchant: Who receives or sends the funds
    • For debits: Merchant receiving customer payment
    • For credits: Merchant/recipient receiving payout
    • Links to Merchant resource
  • Tags: Custom metadata
    • Track orders, campaigns, products
    • Link to external systems
    • Searchable and filterable
    • Not visible to customers
  • Split Transfers: Divide payment among merchants
    • Marketplace/platform payments
    • Specify array of splits
    • Each split has merchant_id and amount
    • Example: $100 order → $75 to Vendor A, $25 to Vendor B
  • Additional Buyer Charges: Extra fees
    • Convenience fees, service fees
    • Separate from base amount
    • Disclosed to customer
    • Example: $100 product + $2 convenience fee = $102 total
  • Level 2/3 Data: Enhanced card data
    • Lowers interchange fees for B2B/B2G
    • Includes tax amount, customer code, line items
    • Optional but recommended for corporate cards
    • Can save 0.5-1% in fees
  • Operation Key: Transaction type
    • CARD_PRESENT_SALE: In-person, card present
      • Lower interchange rates
      • Requires EMV/swipe data
    • CARD_NOT_PRESENT_SALE: Online, card not present
      • Standard online transaction
      • Default for e-commerce

Use Cases​

E-commerce Purchase​

{
  "amount": 4999,
  "currency": "USD",
  "merchant": "MUonline_store",
  "source": "PIcustomer_card",
  "tags": {
    "order_id": "ORD-98765",
    "product_sku": "WIDGET-001"
  }
}
  • Customer buys $49.99 widget
  • Charge customer's card
  • Merchant receives funds (minus fees)

Marketplace Split Payment​

{
  "amount": 10000,
  "currency": "USD",
  "merchant": "MUplatform",
  "source": "PIbuyer_card",
  "split_transfers": [
    {
      "merchant": "MUvendor_a",
      "amount": 7500,
      "tags": {"vendor": "A"}
    },
    {
      "merchant": "MUvendor_b",
      "amount": 2500,
      "tags": {"vendor": "B"}
    }
  ],
  "tags": {
    "marketplace_order": "MP-12345"
  }
}
  • Customer pays $100
  • $75 to Vendor A
  • $25 to Vendor B
  • Platform handles split automatically

Merchant Payout​

{
  "amount": 50000,
  "currency": "USD",
  "merchant": "MUmerchant",
  "destination": "PImerchant_bank_account",
  "tags": {
    "settlement_id": "SETTLE-2023-12",
    "period": "monthly"
  }
}
  • Send $500 to merchant's bank
  • Monthly settlement payout
  • CREDIT type transfer

Subscription Charge with Convenience Fee​

{
  "amount": 9900,
  "currency": "USD",
  "merchant": "MUsaas_company",
  "source": "PIsubscriber_card",
  "additional_buyer_charges": {
    "convenience_fee": 200
  },
  "tags": {
    "subscription_id": "SUB-456",
    "plan": "pro"
  }
}
  • $99 subscription
  • $2 convenience fee
  • Total charge: $101

Best Practices​

  • Idempotency: Store transfer ID to prevent duplicates
  • Amount Validation: Verify amount on server-side
  • Error Handling: Check state after creation
    • PENDING → Poll or use webhooks
    • FAILED → Display error to customer
  • Tags: Always include order/transaction reference
  • Webhooks: Listen for state changes
    • transfer.succeeded
    • transfer.failed
  • Retry Logic: Don't auto-retry failed transfers
    • May result in duplicate charges
    • Let customer retry manually
  • Split Transfers: Verify amounts sum correctly
    • Sum of splits ≤ total amount
    • Platform fee = total - sum(splits)
  • Level 2/3 Data: Use for B2B transactions
    • Can reduce fees by 0.5-1%
    • Requires tax amount, customer code
    • Worthwhile for large transactions

Common Workflows​

Checkout Flow​

  1. Customer adds items to cart
  2. Customer enters payment info
  3. Create Payment Instrument
  4. Create Transfer with source = payment instrument
  5. Check transfer state
  6. If SUCCEEDED: Fulfill order
  7. If FAILED: Display error, allow retry

Failed Payment Handling​

  1. Transfer state = FAILED
  2. Read failure details from response
  3. Display error to customer
  4. Offer retry or alternative payment
  5. Don't auto-retry (risk duplicate charge)

Marketplace Payment​

  1. Calculate order total
  2. Determine vendor splits
  3. Create Transfer with split_transfers array
  4. Platform keeps difference as fee
  5. Vendors receive their portions in settlements
  • GET /transfers: List all transfers
  • GET /transfers/{id}: Fetch transfer details
  • PUT /transfers/{id}: Update tags
  • POST /transfers/{id}/reversals: Create refund
  • GET /transfers/{id}/reversals: List refunds