Create Transfer

OverviewCopy Anchor Link

Transfer points to another member directly (using their member external ID) or create a pending gift transfer (using email or phone). Pending transfers can be claimed by the recipient later when they join or verify their contact information.

AuthenticationCopy Anchor Link

Requires a valid Clerk JWT token in the Authorization header.

SecurityCopy Anchor Link

Reverification Required: This endpoint requires reverification if the user hasn't verified their credentials within the last 10 minutes. This is a sensitive action involving point transfers.

Request BodyCopy Anchor Link

Note: Either toMemberExternalId OR (recipientEmail or recipientPhone) must be provided, but not both.

curl -X POST "http://localhost:3000/v1/members/me/transfers" \
  -H "Authorization: Bearer YOUR_CLERK_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "toMemberExternalId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "amount": 1000,
    "note": "Happy birthday!"
  }'

ResponseCopy Anchor Link

{
  "transferId": "018f1234-5678-9abc-def0-123456789abc",
  "correlationId": "018f1234-5678-9abc-def0-123456789abc",
  "amount": 1000,
  "status": "COMPLETED"
}

Transfer TypesCopy Anchor Link

Direct Transfer (Member-to-Member)Copy Anchor Link

• Recipient: Existing member identified by external ID
• Status: COMPLETED immediately
• Points: Transferred instantly to recipient's account
• Use Case: Send points to known members

Gift Transfer (Pending)Copy Anchor Link

• Recipient: Email or phone number (not yet a member)
• Status: PENDING until claimed
• Expiration: 30 days from creation
• Points: Held in escrow until claimed or expired
• Use Case: Gift points to friends who aren't members yet

Validation RulesCopy Anchor Link

Amount LimitsCopy Anchor Link

• Minimum: 1 point
• Maximum: Based on your tier and transfer limits
• Check: Use Get Transfer Limits to verify

Recipient ValidationCopy Anchor Link

• Member External ID: Must be valid 26-character ULID
• Email: Must be valid email format
• Phone: Must be valid E.164 format
• Self Transfer: Cannot transfer to yourself

Balance CheckCopy Anchor Link

• Sufficient Balance: Must have enough VALID points
• Real-time: Balance checked at transfer time
• Type: Only VALID points can be transferred (not CREDIT points)

Error HandlingCopy Anchor Link

Common ErrorsCopy Anchor Link

Rate LimitingCopy Anchor Link

• No specific rate limit for transfers
• Security measures in place for fraud prevention
• Reverification required for sensitive actions

Use CasesCopy Anchor Link

Send Birthday GiftCopy Anchor Link

const sendBirthdayGift = async (recipientEmail: string, amount: number) => {
  try {
    const response = await fetch('/api/members/me/transfers', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        recipientEmail,
        amount,
        note: '🎂 Happy Birthday! Enjoy some points on me!'
      })
    });
    
    const result = await response.json();
    
    if (response.ok) {
      console.log(`Gift sent! Transfer ID: ${result.transferId}`);
      console.log(`Status: ${result.status}`);
      if (result.expiresAt) {
        console.log(`Expires: ${result.expiresAt}`);
      }
    } else {
      handleTransferError(result);
    }
  } catch (error) {
    console.error('Failed to send gift:', error);
  }
};

Transfer to Known MemberCopy Anchor Link

const transferToMember = async (memberExternalId: string, amount: number, note: string) => {
  try {
    const response = await fetch('/api/members/me/transfers', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        toMemberExternalId: memberExternalId,
        amount,
        note
      })
    });
    
    const result = await response.json();
    
    if (response.ok && result.status === 'COMPLETED') {
      console.log(`Transfer completed! ${amount} points sent.`);
    }
  } catch (error) {
    console.error('Transfer failed:', error);
  }
};

Bulk Gift CampaignCopy Anchor Link

const sendBulkGifts = async (recipients: Array<{email: string, amount: number}>) => {
  const results = await Promise.allSettled(
    recipients.map(({email, amount}) => 
      fetch('/api/members/me/transfers', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          recipientEmail: email,
          amount,
          note: 'Thank you for being an amazing customer!'
        })
      })
    )
  );
  
  const successful = results.filter(r => r.status === 'fulfilled').length;
  console.log(`${successful}/${recipients.length} gifts sent successfully`);
};

Security NotesCopy Anchor Link

ReverificationCopy Anchor Link

• Required: For all transfer operations
• Timeframe: Within last 10 minutes
• Methods: SMS OTP or email verification
• Bypass: Not possible for security reasons

Fraud PreventionCopy Anchor Link

• Monitoring: Unusual transfer patterns detected
• Limits: Daily and monthly transfer limits enforced
• Validation: Recipient verification for suspicious activity

Related EndpointsCopy Anchor Link

• Get Transfer Limits - Check your transfer limits before sending
• Member Lookup - Find member details before transferring
• List Pending Transfers - View your pending transfers
• Claim Pending Transfer - Claim gifts sent to you