create_referenced_payout

Create PayPal payouts linked to specific references like orders or invoices, enabling automated payment processing with traceable transaction records.

Instructions

Create a referenced payout

Input Schema

TableJSON Schema

Name	Required	Description	Default
`referenced_payouts`	Yes

Implementation Reference

src/index.ts:1199-1212 (handler)

Handler implementation in the switch statement that validates arguments, makes POST request to PayPal API for referenced payouts, and returns the response.

case 'create_referenced_payout': {
  const args = this.validateReferencedPayout(request.params.arguments);
  const response = await axios.post<PayPalReferencedPayout>(
    'https://api-m.sandbox.paypal.com/v1/payments/referenced-payouts',
    args,
    { headers }
  );
  return {
    content: [{
      type: 'text',
      text: JSON.stringify(response.data, null, 2)
    }]
  };
}

src/index.ts:914-942 (registration)

Tool registration object defining name, description, and input schema for create_referenced_payout.

{
  name: 'create_referenced_payout',
  description: 'Create a referenced payout',
  inputSchema: {
    type: 'object',
    properties: {
      referenced_payouts: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            reference_id: { type: 'string' },
            reference_type: { type: 'string' },
            payout_amount: {
              type: 'object',
              properties: {
                currency_code: { type: 'string' },
                value: { type: 'string' }
              },
              required: ['currency_code', 'value']
            },
            payout_destination: { type: 'string' }
          },
          required: ['reference_id', 'reference_type', 'payout_amount', 'payout_destination']
        }
      }
    },
    required: ['referenced_payouts']
  }

src/index.ts:462-506 (helper)

Helper function for validating and formatting input arguments for the create_referenced_payout tool.

private validateReferencedPayout(args: unknown): PayPalReferencedPayout {
  if (typeof args !== 'object' || !args) {
    throw new McpError(ErrorCode.InvalidParams, 'Invalid referenced payout data');
  }

  const payout = args as Record<string, unknown>;
  
  if (!Array.isArray(payout.referenced_payouts) || payout.referenced_payouts.length === 0) {
    throw new McpError(ErrorCode.InvalidParams, 'Missing referenced payouts');
  }

  const referenced_payouts = payout.referenced_payouts.map(ref => {
    const refPayout = ref as Record<string, unknown>;
    if (typeof refPayout.reference_id !== 'string' ||
        typeof refPayout.reference_type !== 'string' ||
        !refPayout.payout_amount || typeof refPayout.payout_amount !== 'object' ||
        typeof refPayout.payout_destination !== 'string') {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid referenced payout');
    }

    const amount = refPayout.payout_amount as Record<string, unknown>;
    if (typeof amount.currency_code !== 'string' || typeof amount.value !== 'string') {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid amount fields');
    }

    return {
      item_id: typeof refPayout.item_id === 'string' ? refPayout.item_id : '',
      processing_state: {
        status: typeof refPayout.processing_state === 'object' ? 
          (refPayout.processing_state as any).status || '' : '',
        reason: typeof refPayout.processing_state === 'object' ? 
          (refPayout.processing_state as any).reason : undefined
      },
      reference_id: refPayout.reference_id,
      reference_type: refPayout.reference_type,
      payout_amount: {
        currency_code: amount.currency_code,
        value: amount.value
      },
      payout_destination: refPayout.payout_destination
    };
  });

  return { referenced_payouts };
}

PayPal MCP